Recipients

A Recipient within Knock is any User or Object that may wish to receive notifications. Knock persists information about recipients to send those recipients notifications and give a single source of truth for the notifications sent for debugging and logging purposes.

Recipients have:

• Identifiers. A string from your system that uniquely represents the recipient.
• Properties. Structured and unstructured data for the recipient, including but not limited to the name, email, and phone number.
• Preferences. The rules under which the recipient should or should not receive notifications.
• Channel data. Channel data send a recipient a notification on a particular channel, such as tokens for sending push notifications to a given channel or access tokens to send notifications to a chat channel like Slack.

A recipient identifier can be one of:

• A string user ID for a previously identified user (user-1)
• An object reference dictionary ({ "collection": "my-collection", "id": "object-1" }) for a previously identified object
• A dictionary containing a recipient to be identified inline

This can be expressed as the following type:

For Knock to be able to send notifications to your recipients, you must first identify those recipients to synchronize them with Knock. We call this process "identification", and it can be done ahead of time, or lazily via inline-identification in your workflow triggers. Identifying sets the properties associated with your recipients into Knock, so that you can reference those properties in the notifications you send out.

Read more about identifying your recipients ->

Recipients in Knock can have any number of custom properties set on them, which you set during the identification process. Some properties, like email or phone_number are required for notifications to be delivered to the recipient.

You can use our Subscriptions feature to create a Knock-managed list of recipients that should be notified. Subscriptions are useful for modeling pub/sub behavior.

A recipient can have an optional timezone property, which should be a valid tz database time zone string, like America/New_York or Europe/London. By default, if no recipient timezone is set Etc/UTC will be used however a default timezone can be specified at the account level under "Settings" which will override this default for all recipients.