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.
RecipientIdentifier definiton
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:
Ahead-of-time identifying recipients
Recipients should be identified to Knock so that Knock can execute workflows for those recipients. You can see more in the documentation for both users and objects on how to individually and bulk identify.
Inline identifying recipients
A recipient can be passed inline when triggering a workflow or when subscribing a recipient to an object.
An inline identify causes to Knock to create/update the recipient before completing the action in which the inline identify is taking place (e.g. the workflow trigger).
In the example above, when this set of recipients are passed to Knock we first upsert the two users, creating or replacing the properties sent.
Setting preferences inline
When inline identifying a recipient, one or more preference sets can also be supplied for the recipient, upserting any existing preferences set for the recipient.
Note: the preference set id must always be supplied in the dictionary of preferences sent, which in the example above is default.
Setting channel data inline
Along with preferences, channel data can also be specified inline along with a RecipientIdentifier, replacing any existing channel data set for the channels given.
Note: the key in the channel data dictionary is the channel ID of a valid channel you've created within Knock. You can find a channel's ID on its channel page ("Integrations" > "Channels").
Managing lists of recipients
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.
Recipient timezones
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.
Frequently asked questions
Is there a limit on the number of recipients I can have in Knock?
No, there's no limit on the number of recipients you can have within Knock.
Why would I need a non-user recipient?
We support non-user entities (Objects) receiving notifications in Knock because some notifications are delivered to non-user entities. For example, a Slack notification that sends to a channel. That notification is not delivered to a user but to an entity that connects Slack and your system (such as a Project or a Team).
Is there a limit to the size of the properties I can pass on a recipient to Knock?
Currently, there's no limit to the size of the properties you can add to a recipient. We reserve the right to impose a limit here in the future, however.