A Preference determines whether a given recipient (a user or an object) will receive a notification for a given workflow, channel, or workflow-channel pair.
In this guide we'll walk through how to set notification preferences for your recipients in Knock.
We'll start with a quick overview of the preferences model and how it ties into the rest of Knock, then we'll walk through how to set notification preferences for workflows, categories, and channels, as well as combinations of all three.
There are three different types of preferences we can set for our recipients in Knock: channel type preferences, workflow preferences, and workflow category preferences.
To see how they work let's start with a review of how Knock sends notifications to your recipients. You configure a workflow in Knock. When this workflow is called via a workflow trigger, it runs for every recipient sent in the triggering API call, sending them a notification on each channel configured in the workflow.
Preferences are per-recipient rules that tell Knock whether a notification should be delivered to a recipient based on its channel type, its workflow, and the workflow category that workflow belongs to (if any).
When the channel step executes in your workflow run, the recipient will only receive a notification if their preferences for the channel type, the workflow, and the workflow category all evaluate to
true. To put this in inverse terms, if ANY preference related to a given channel step in a workflow evaluates to
false, we will not send the recipient a notification. This makes sense, as receiving a notification you thought you opted out of is not a fun experience for recipients. 😁 (Note: if you do not set a preference for a given channel, workflow, or category, Knock defaults them to
In the next section, we'll walk through this evaluation model in more detail and outline how to set preferences via the Knock preferences API.
As mentioned in the previous section, there are three types of preferences you can set for your recipients: channel type, workflow, and workflow category. You can also use these preference types in combination with one another. We cover that below, too.
A channel type preference lets recipients opt out of notifications for an entire 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
Here's a JSON example of a given recipients's channel preferences.
In this example, the recipient wouldn't receive any notifications sent over email, as any email channel steps, regardless of their workflow or workflow category, would always evaluate to
false. This makes channel preferences a good way to give your recipients a way to opt-out of ALL notifications sent across a given channel type, such as email or push. Once a recipient is opted into a channel type, you're relying on workflow and workflow category preferences to determine whether a given notification should be sent.
A workflow preference can be set for a specific workflow (e.g. a mention). When a recipient's preference for a given workflow is set to
false, the recipient will not receive any notifications generated by that workflow across any channel type.
Here's a JSON example of a given recipient's workflow preferences.
In this example, the recipient 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 recipients a way to opt out of a given notification or type of notification across ALL channels.
There are cases when you'll want to enable your recipients to set a preference for a category of workflows, for example, all of your workflows related to
direct notifications. In these cases, rather than having to surface a preference control for each of those notification types, you can use
categories to set the preference for multiple workflows at once.
To set a category for a given workflow, go to that workflow's page in the dashboard, click the "..." menu, and select "Manage workflow". From there you'll be able to add categories. (Note: A workflow can belong to multiple categories. In the instance that it does, and conflicting preferences are set across those categories, the workflow's preference will default to false.)
Here's an example of a given recipient's preferences for a set of workflow categories.
truefor the notification to send.
In many cases, you'll want to let recipients pick and choose which channels they want to be notified on about which workflows or workflow categories. This way they can opt into more disruptive channels (such as email and push) for notifications they deem important, and they can opt out of those channels on notifications they deem less important.
This is where you can combine preferences. When you want to enable a recipient to choose which channels they want to be notified on for a given workflow or category, you can specify a
channel_types object within both the
Take an example of an app that wants to give per-channel preferences to its recipients on both its
new-mention workflow and on its
collaboration category. In the example below, the recipient has decided they want to receive mention notifications on all channels, but collaboration notifications on just the in-app channel.
Remember: in cases where a preference is set both for a workflow and for its parent category, Knock will only send a notification if all preference combinations that exist on the recipient evaluate to
true. This means that in the case above, if the
new-mention workflow belongs to the
collaboration category, the recipient will not receive email notifications about new mentions, even though the preference is currently set to
When working with preferences, you’ll sometimes run into advanced use cases where you need to provide even more granular preference options for your customers. For example: you may want to let a recipient mute notifications about a given resource in your product. That’s where preference conditions come into use in the Knock model: they provide a powerful way for you to add extra logic that’s computed during preference evaluation per recipient.
A condition is one or more pieces of logic that are evaluated when computing the current state of a preference. Typically, preferences evaluate to boolean values representing if the recipient has opted in or out of receiving notifications on a given channel, workflow, or category. With preference conditions, you can add additional custom expressions to that set, where the notification is only sent if all preferences (including the preference condition statement) evaluate to true.
Note: multiple conditions are evaluated as
- Reference data passed in your workflow trigger (the
- Reference data stored on the
- Evaluate against fixed values like booleans, strings, and integers
- Evaluate against various types of operators, like ==, ≠, IN, NOT IN and more
A condition can be applied at different points in the preference set:
- Inside an individual
- Inside an individual
You can use any of the following in arguments or variables:
recipient.*- target a property in the recipient
actor.*- target a property in the actor
data.*- target a property in the data payload
refs.*- target the result of a previous step
You can use any of the following operators in condition comparisons: