KnockDocs

Setting channel data

Some channel integrations require user and channel specific data in order 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 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 the 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 "Channels". Once the channel for which you want to store channel data has been created, you're ready to setChannelData for your users and objects.

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.

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.


👩‍💻
See an example. Check out our example app to see how to integrate with Slack by setting channel data with an incoming webhook URL.

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

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 users device.

APNS (Apple Push Notification Service)

PropertyTypeDescription
tokens*string[]One or more device tokens

FCM (Firebase Cloud Messaging)

PropertyTypeDescription
tokens*string[]One or more device tokens

Expo

PropertyTypeDescription
tokens*string[]One or more device tokens

Chat app channels

As of today, we only support Slack within our chat channel type. We have support for Discord and Microsoft Teams coming soon.

Slack

PropertyTypeDescription
connectionsSlackConnection[]One or more connections to Slack

A SlackConnection has the following schema:

PropertyTypeDescription
access_tokenstringA bot access token
channel_idstringA Slack channel ID
user_idstringA Slack user ID
incoming_webhook.urlstringThe Slack incoming webhook URL (to be used instead of the properties above)