Managing recipients
Setting channel data

Setting channel data

Learn about how to set channel data for your recipients and users to make it easy to connect recipients with push and chat channels.

Some channel integrations require user and channel-specific data to send notifications. Push channels like APNs (Apple Push Notification Service) and FCM (Firebase Cloud Messaging) are good examples, where both require that there are device-specific tokens that target the user in a push notification. Slack is another good example, where the channel data from a Slack integration in your product is stored on a Knock object.

At Knock we call this concept ChannelData. ChannelData lives under a user or an object and stores channel-specific data to be used when that user or object is included as a recipient on a triggered workflow.

Things to know about channel data

  • For channel types that require channel data (such as push channels and chat channels like Slack), the channel step will be skipped during a workflow run if the required channel_data is not stored on the recipient.
  • Knock stores channel data for you but makes no assumptions about whether the stored channel data is valid. That means that if a push token expires, it's your responsibility to omit/update that token for future notifications.
    • For push providers, Knock offers an opt-in token deregistration feature that automatically removes invalid tokens from a recipient's channel data when messages bounce.
  • Setting channel data always requires a channel_id, which can be obtained in the Dashboard under Integrations > Channels. A channel ID is always a UUID v4.

Setting channel data

Before getting or setting channel data, you must first configure that channel in your environments. You can do this inside the Knock dashboard under Integrations > Channels. Once the channel for which you want to store channel data has been created, you're ready to store the channel data for your users and objects.

There are three ways of setting channel data for a given recipient:

  1. Explicitly using the set channel data method
  2. Inline through a workflow trigger
  3. When identifying a recipient

You can set channel data for a given user using the users.setChannelData method. Please note that the channel data will always be overwritten with each set call.

In the example below, we're setting a user's device token when they download our mobile app so we can send them push notifications. If this token wasn't set for the user, they wouldn't receive push notifications from our notification workflows.

You can set channel data for a given object using the objects.setChannelData method. Please note that the channel data will always be overwritten with each set call.

In the example below, we're setting an object's Slack channel ID and access token, presumably after a user in our product has decided to connect the object to their Slack workspace. This enables us to send Slack notifications to the connected Slack channel when an event is triggered within the scope of the object.

You can learn more about objects in our concept guide and API reference.

For both user and object recipients, channel data can be specified inline during a workflow trigger call.

When setting channel data inline for a recipient entity, you must supply the channel data as a dictionary containing the channel ID as a key, and a dictionary of channel data to set for that channel.

For both user and object recipients, channel data can be specified as a recipient property on an identify request.

When setting channel data for a recipient entity on an identify request, you must supply the channel data as a dictionary containing the channel ID as a key, and a dictionary of channel data to set for that channel. The below example is for a User, but the same pattern can be followed for an Object.

Getting channel data

To retrieve the currently set channel data, you can use the getChannelData method on users and objects. If channel data is not set for the recipient you'll receive a 404 response.

Clearing channel data

Any previously set channel data can be cleared by issuing an unsetChannelData call. Unsetting channel data for a recipient requires a valid channel ID to be passed.

Provider data requirements

Channel data requirements for each provider are listed below. Typically channel_data comprises a token or other value that is used to uniquely identify a user's device.

Push channels

PropertyTypeDescription
tokens*string[]One or more device tokens
PropertyTypeDescription
tokens*string[]One or more device tokens
PropertyTypeDescription
tokens*string[]One or more device tokens
PropertyTypeDescription
player_ids*string[]One or more player_ids

Chat app channels

PropertyTypeDescription
connectionsSlackConnection[]One or more connections to Slack

A SlackConnection can have one of two schemas, depending on whether you're using standard Slack OAuth scopes or an incoming webhook. We cover Slack app scopes in detail in our Slack scopes guide.

If you're using standard Slack OAuth with access token scopes, your SlackConnection schema looks like this. You'll use either a channel_id or user_id depending on whether you're storing connection data to message a channel or user in Slack:

PropertyTypeDescription
access_tokenstringA bot access token
channel_idstringA Slack channel ID
user_idstringA Slack user ID

If you're using a Slack app with the incoming-webhook scope your SlackConnection schema is quite simple:

PropertyTypeDescription
incoming_webhook.urlstringThe Slack incoming webhook URL (to be used instead of the properties above)
PropertyTypeDescription
connectionsDiscordConnection[]One or more connections to Discord

A DiscordConnection has the following schema:

PropertyTypeDescription
channel_idstringA Discord channel ID
incoming_webhook.urlstringThe Discord incoming webhook URL (to be used instead of the properties above)
PropertyTypeDescription
connectionsMsTeamsConnection[]One or more connections to MsTeams

An MsTeamsConnection can have one of two schemas, depending on whether you're using a Microsoft Teams bot or an incoming webhook.

If you're using a Microsoft Teams bot, your MsTeamsConnection schema looks like this. You'll use either ms_teams_channel_id or ms_teams_user_id depending on whether you're storing connection data to message a channel or user in Microsoft Teams:

PropertyTypeDescription
ms_teams_tenant_idstringA Microsoft Entra tenant ID
ms_teams_team_idstringA Microsoft Teams team ID
ms_teams_channel_idstringA Microsoft Teams channel ID
ms_teams_user_idstringA Microsoft Teams user ID

If you're using an incoming webhook, your MsTeamsConnection schema is quite simple:

PropertyTypeDescription
incoming_webhook.urlstringThe Microsoft Teams incoming webhook URL (to be used instead of the properties above)