In this guide we'll walk through how to set notification preferences for your users in Knock.
We'll start with a quick overview of the preferences model and how it ties into the rest of Knock, then walkthrough how to set notification preferences for notifications, channels, and notification-channel pairs using the preferences endpoint.
To start, let's review how Knock sends notifications to your users. You configure a workflow in Knock. When this workflow is called via the notify endpoint, it runs for every recipient sent in the notify call, sending them a notification on each channel configured in the workflow.
Preferences are per-user rules that tell a workflow whether a notification should be delivered to a user based on (i) the channel type over which the notification is being sent and (ii) the workflow from which the notification is being sent.
We can work back from this definition to arrive at three types of preferences that we can set for our users in Knock: channel type preferences, workflow preferences, and workflow-channel preferences.
In the next section, we'll walk through each of these in more detail and outline how to set these preferences via the Knock preferences API.
As mentioned in the previous section, there are three types of preferences you can set for your users: channel type, workflow, and workflow-channel.
A channel type preference is a notification preference set for a channel type. You can set preferences for all unique channel types configured within your account. (As an example, if I have three channels configured of type
push , and one channel configured of type
in_app_feed , we can set channel preferences for email, push, and in_app_feed.)
When a channel type's subscribed preference is false, all notifications sent across that channel will follow the preference, irrespective of the workflow they come from. Or in other words, "once a user unsubscribes from a channel, they won't receive any notifications from that channel."
When a channel type's subscribed preference is true, all notifications sent across that channel will defer to the user's workflow-level preference. More on this later. (Note: if a user's preference is not set for a given channel type, Knock defaults to opting the user into that channel type.)
Here's a JSON example of a given user's channel preferences.
In this example, the user wouldn't receive any notifications sent over email. The user would receive in-app notifications as long as they aren't unsubscribed from the notification being sent.
In summary, channel preferences are a helpful way to give your users a way to opt-out of ALL notifications sent across a given channel type, such as email or desktop push. When a user is opted into a channel type, any relevant workflow preferences are checked before sending a notification to the end user.
A workflow preference can be set for a specific workflow (e.g. an @-mention). When a workflow's subscribed preference is set to false, the user will not receive any notifications generated by the corresponding workflow, across any channel type.
When a workflow's subscribed preference is set to true, the user will receive notifications generated by that workflow on any channels where they have opted-in to notifications.
Here's a JSON example of a given user's workflow preferences.
In this example, the user would not receive any notifications from the new-reply workflow but would receive notifications from the new-comment workflow.
Workflow preferences are a great way to give your users a way to opt-out of a given notification or type of notification across ALL channels.
In some cases, users want to unsubscribe from an entire channel altogether. In others, they want to pick and choose which notifications they receive over a given channel. This is where workflow-channel preferences come in—they enable a user to decide on which channels they want to receive a given workflow's notifications.
When a workflow-channel preference is set to subscribed, the user receives all notifications sent to that channel by the specified workflow.
Here's a JSON example of a given user's workflow-channel preference.
In this example, the user would receive in-app notifications but not email notifications for the new-comment workflow.
Based on what we've discussed above, you can follow the preference evaluation rules below to understand how a given user's preferences will evaluate for a given workflow-channel combination.
- Is the user opted out of the current channel? If so, don't send the notification.
- Is the user opted out of the notifications sent by the current workflow? If so, don't send the notification.
- Is the user opted out of the current workflow-channel pair? If so, don't send the notification.