Preferences
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.
An overview of preferences
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 a 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. Read more about preferences evaluation here.
true
.Where preferences can be set
Preferences can be set at three different levels in Knock:
- At the environment level, as the default for all recipients in a given environment
- At the tenant level, as the default for all recipients when a
tenant
is applied to a workflow trigger - At the recipient level, as the default for that recipient or as per-tenant preferences for that recipient
Types of preferences
There are three different types of preferences we can set for our recipients in Knock: channel type preferences, workflow preferences, and workflow category preferences. You can also use these preference types in combination with one another.
Channel type preferences
A channel type preference lets recipients opt out of all notifications for an entire channel type, such as email. You can set preferences for all unique channel types configured within your account.
For example, if I have three configured channels of type email
, two of type push
, and one of type in_app_feed
, we can set channel preferences for email
, push
, and in_app_feed
.
Here's a JSON example of a given recipient'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
.
Workflow preferences
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 type of notification across all channels.
Workflow category preferences
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.
Here's an example of a given recipient's preferences for a set of workflow categories:
Combining preferences
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.
When you want to enable a recipient to choose which channels they'll be notified on for a given workflow or category, you can specify a channel_types
object within both the workflows
and categories
preferences.
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.
Recipient preference sets
A PreferenceSet
is the object that stores all of a recipient's preferences. When you set a given user's preferences in Knock, you can either set their default
preferences or create a tenant
-specific preference set.
user
preferences, all of this information applies to object
preferences as well.default
preference set
The An individual user's default
preference set is used to define the preferences that the Knock notification engine will default to when evaluating whether to send a notification to a given user across a given channel.
The Knock notification engine uses the default
preference set for preference evaluation when:
- No
tenant
was specified on the workflow trigger that started the workflow run - The recipient does not have a specified preference set for the
tenant
that was provided on the workflow trigger
If your product only gives users a single set of notification preferences to configure across all tenants in your product, you'll just be using the default
scope for your users' preferences.
id
when creating/updating a preference set, the default
preference set will be used.Per-tenant preference sets
In some cases you may want to set additional preferences for a given user that pertain to a specific tenant
within your product. A well-known example of this: in Slack, your notification preferences are set per Slack workspace, not as global preferences that apply across all of your Slack workspaces.
To create a preference set scoped to a particular Tenant, you'll set the id
of the recipient's preference set equal to the tenant.id
.
The Knock notification engine uses a per-tenant preference set for preference evaluation when the recipient
of the workflow run has a preference set with an id
equal to the tenant.id
that is provided on the workflow trigger.
Preference defaults
Often you'll want new users in your product to start with a default preference set that you specify. This can be done at both the environment and tenant level.
Environment-level preference defaults
When a user is created in Knock, they are automatically opted into all channel types. This means their preference set looks like this:
In the event you need to update this set of default preferences, you can do so from the Developers > Preferences section of the dashboard. From here you can specify a default set of preferences per environment that will be applied to all recipients when executing a notification workflow. The default preferences set in the dashboard follow the same shape as any preferences you set via the API and will be validated before being saved.
Default preferences are useful when you need to roll out preferences across all your recipients or need to migrate recipients from one preference model to another. It's important to remember that for more complex preference migrations you may still need to update any stored preferences for your recipients, which you can do via the batch preference update API.
Per-tenant preference defaults
In some cases, you may want to extend Knock's default preference behavior to your tenant admins to let them choose the notification preference defaults for users within their tenants in your product.
You can use tenant preference defaults to set the default preferences inherited for all recipients of a workflow triggered with a corresponding tenant
.
Evaluating preferences
When a workflow is triggered, Knock will evaluate the preferences for each recipient
of the workflow and send notifications for each channel step in the workflow based on that evaluation. There are some important rules and caveats to consider:
Advanced preferences topics
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.
Preference conditions
Preference conditions are Knock condition models that are evaluated when computing the current state of your preferences during workflow execution.
Typically, preferences evaluate to boolean values representing if your 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
.
Below is an example of a workflow preference that has conditions applied to determine if the preference is true
or false
:
Overriding recipient preferences
Sometimes you may want to override a recipient's notification preferences in order to send notifications like a password reset email, regardless of whether the recipient has opted out of receiving emails. To do this, go to your workflow, click "Manage workflow", and enable "Override recipient preferences". You will need to commit this change for it to take effect.
When enabled, the workflow will send to all of its channels, regardless of the recipient's preferences.