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.
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)
| Property | Type | Description |
|---|---|---|
| tokens* | string[] | One or more device tokens |
FCM (Firebase Cloud Messaging)
| Property | Type | Description |
|---|---|---|
| tokens* | string[] | One or more device tokens |
Expo
| Property | Type | Description |
|---|---|---|
| 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
| Property | Type | Description |
|---|---|---|
| connections | SlackConnection[] | One or more connections to Slack |
A SlackConnection has the following schema:
| Property | Type | Description |
|---|---|---|
| access_token | string | A bot access token |
| channel_id | string | A Slack channel ID |
| user_id | string | A Slack user ID |
| incoming_webhook.url | string | The Slack incoming webhook URL (to be used instead of the properties above) |