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. 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 and chat channels like Slack), the channel step will be skipped in 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.

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 two ways of setting channel data for a given recipient:

1. Explicitly using the set channel data method
2. Inline through a workflow trigger

Note: channel data always requires a channelId which can be obtained in the Dashboard under Integrations > Channels. A channel ID is always a UUID v4.

Explicitly setting for users

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.

Explicitly setting for objects

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.

Setting channel data inline

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.

Getting channel data

To retrieve the currently set channel data you can use the getChannelData method on users and objects. Note: if the channel data is not set for the user/object you'll receive a 404.

User usage

Object usage

Clearing channel data

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

Provider data requirements

Push channels

Channel data requirements for each push provider are listed below. Typically this means setting one or more tokens to uniquely identify a user's device.

APNS (Apple Push Notification Service)

FCM (Firebase Cloud Messaging)

Expo

Chat app channels

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.

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

Discord

A DiscordConnection has the following schema:

Microsoft Teams

A MsTeamsConnection has the following schema: