Setting channel data

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. For most channels, 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. For chat providers that support tenant-stored credentials, ChannelData can also live on a tenant to provide shared auth while the recipient stores the destination.

• 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 the Channels and sources page in your account settings. A channel ID is always a UUID v4.

Before getting or setting channel data, you must first configure that channel in your environments. You can do this inside the Knock dashboard under the Channels and sources page in your account settings. 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

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.

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.

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

You can set push channel data by passing either:

• A list of tokens (or target_arns for Amazon SNS) strings
• A list of devices objects for supported push providers. If set, this device-level metadata will be used when evaluating translations and send windows.

The PushDevice object is used to optionally set device-level metadata for a push channel. It contains the following properties:

Property	Type	Description
token*	string	The device token to send the push notification to. Required for providers other than Amazon SNS.
target_arn*	string	The ARN of a platform endpoint associated with a platform application and a device token. Required for Amazon SNS.
locale	string	The locale of the device.
timezone	string	The timezone of the device. Must be a valid tz database time zone string.

In a multi-tenant application, the same recipient may need a different chat destination for each tenant. For example, a project object might send notifications to #project-updates in Acme's Slack workspace and #engineering in Globex's workspace.

For Slack, Microsoft Teams, and Discord, add an optional knock_tenant_id to each connection stored on the recipient. Set it to the ID of the Knock tenant that should use that connection. knock_tenant_id scopes the whole connection, including bot-based destinations and incoming webhooks. It is distinct from provider identifiers such as Microsoft Teams' ms_teams_tenant_id.

Use the set channel data API for an object or user, or use a server-side SDK, to include knock_tenant_id in each connection:

The same field works when you set channel data on a user. Because setting channel data replaces the existing data for that channel, include every connection you want to retain in the request.

When you trigger a workflow with a tenant, Knock selects recipient connections as follows:

Workflow trigger	Connections Knock uses
Includes tenant acme and one or more connections match it	All connections where knock_tenant_id is acme
Includes tenant acme, but no connections match it	Untagged connections, including connections with a blank tenant ID
Does not include a tenant	All connections, whether they are tagged or untagged

Knock never uses a connection tagged for a different tenant when the workflow trigger includes a tenant. If several connections match, the chat step fans out to all of them. The knock_tenant_id does not set or infer the tenant for a workflow run; you must still include the tenant in the workflow trigger.

Tenant-scoped connections work with a Slack access token or Microsoft Entra tenant ID stored on the tenant. Knock selects the recipient connections first, then applies the credentials stored on the trigger's tenant.