Identifying recipients

Learn more about how to identify your user and object recipients to power your notifications.

To send notifications to a recipient (or to reference a recipient as an actor in a notification), Knock needs the recipient's data to be stored in Knock. This process is known as identifying and works across user and object recipients.

There are three different methods to identify recipients:

  • Individual identification
  • Bulk identification
  • Inline identification

In this guide we discuss each of these methods.

🌠
Note: all identification methods in Knock use an upsert approach. This means any existing data for a recipient is merged during the upsert operation.

Explicitly identifying recipients

Individually identifying recipients

You can use the individual identification API to upsert a single recipient's data into Knock. The individual identify API is useful to ensure that user data is updated on an ongoing basis, like when a user updates their profile information inside of your product and you need to ensure it's reflected within Knock.

API reference ->

Bulk identifying recipients

While identifying individual recipients is useful, you may also need to identify multiple recipients at once. This can be useful when you're importing data into Knock to get started.

API reference ->

Inline identifying recipients

It's also possible to inline identify recipients while issuing calls to certain resources within Knock. Inline identifying will always upsert the recipients being passed in before executing the remainder of the request. This can be useful for ensuring that your recipients exist within Knock before executing calls that reference those recipients.

You can also inline identify actors in the same way.

Inline identification works with any endpoint that accepts a list of recipients:

API reference ->

How inline identification works

When passing a set of recipients to be inline identified, Knock will guarantee that the recipients are identified before any other action is executed. That makes it possible to lazily create recipients within Knock using inline identification, only creating them when needed.

Setting properties while identifying recipients

When identifying recipients you pass a set of properties for the recipient that are persisted. No properties on the recipient are required except for id. Generally, the best practice here is to use your internal identifier for your users as the id.

🙈
Note: Although an id is the only required recipient property, triggering a workflow for a recipient which has only an id and no other properties can result in channel steps other than an In-app feed being skipped. This occurs when Knock does not have the necessary recipient data to deliver a notification.

There are some reserved property names for recipients that have special meaning:

  • name: The given name of the recipient
  • email: A valid email address to deliver email notifications to
  • locale: A locale code for the recipient, used for internationalizing content
  • phone_number: A E.164 compliant phone number field used when sending SMS messages
  • created_at: An ISO-8601 datetime of when the recipient was created

A recipient also accepts any number of custom properties, which are key-value pairs that you define. It's useful to store custom properties on your recipients so that you can reference these attributes when sending notifications, or for use in message templates.

Setting preferences and channel data

It's also possible to set preferences and channel data for a recipient during the identification process.

Preferences are passed as a dictionary under the preferences key, where the key represents the preference set id:

Channel data is passed as a dictionary under the channel_data key, where the key represents the channel id:

When to identify recipients in Knock

Knock provides a flexible set of APIs for you to manage your user data as you scale with us. Ultimately, it's up to you to decide upon the best approach for how you manage your user data with Knock.

Below we discuss some common scenarios to consider.

Initial setup: inline vs. bulk identification

When you're first getting started with Knock, you'll likely have a number of existing recipients that you want to migrate into Knock. If you're looking to get started with Knock quickly, you can use inline identification to start calling your workflows without any prerequisite calls to the Knock API.

If you first want to get all your recipients into Knock, the easiest path forward would be via our bulk identification flow.

Identifying recipients on an ongoing basis: jobs vs. inline identification

Once you've migrated your current recipients into Knock, you'll want to continue to update this data in Knock for two key cases:

  1. When new recipients sign up for your product.
  2. When Knock-relevant data about a user changes, like a name or an email address.

One common approach is to make subsequent calls to the Knock's user identify API following such events. For example, you could do this via a deferred job in your backend systems.

Another option is to offload these updates to your workflow trigger calls via inline identification. If you always send Knock the full set of data for your recipients via workflow trigger calls, you can keep your user data up to date in Knock without any additional handling on your end.

Frequently asked questions

←Overview
Setting channel data→