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.

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.

An overview 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.

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 true.)

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.

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.

Channel type preferences

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 email, two 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.)

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

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 notification or 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.

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: workflow categories are case sensitive.

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.

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.

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

Preference sets

When you set a given user's preferences in Knock you can either set a user's default preferences or create a per-tenant preference set.

The default preference set

A user's default preference set is used to define the preference set that the Knock notification engine will default to when evaluating whether to send a notification to a given user across a given channel. (Note: If you're using a Knock SDK and don't specify an id when creating/updating a preference set, the default preference set will be used.)

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
• OR the tenant that was specified on the workflow trigger does not have a specified preference set for that recipient

If your product just 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.

Per-tenant user preference sets

In some cases you may want to set an additional preference set for a given user that pertains 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 a global preference set that applies across all of your Slack workspaces.)

To create a preference set scoped to a particular Tenant, you'll set the id of the preference set equal to tenant.id when you create the preference set for your user.

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 defined on the workflow trigger.

Preference conditions

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. These 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:

Where can I use preference conditions?

A condition can be applied at different points in the preference set:

• Inside workflows, categories, or channel_types preferences
• Inside an individual workflows[workflow].channel_types preference
• Inside an individual categories[category].channel_types preference

See our guide on setting and managing preferences for more details on how to manage preference conditions via the Knock API and SDKs.

Debugging preference conditions

Knock will capture conditions evaluation details for all preference conditions resolved while executing your workflows. See the guide on debugging conditions for more info.

Preference defaults

Often you'll want new users in your product to start with a default preference set that you specify. Preference defaults are a great use case for this. Below we cover environment-level preference defaults, as well as per-tenant preference defaults.

Environment-level preference defaults

When a user is created in Knock, by default they are 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 > Defaults" 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 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 environment-level preference defaults behavior to your tenant admins to let them choose the notification preference defaults for users within their tenants in your product. This is where tenant preference defaults come in.

You can use tenant preference defaults to set the default preferences inherited for all recipients of a workflow triggered with a corresponding tenant.

Setting tenant default preferences

Tenant default preferences can be set via the API by calling the tenants.set method. The preferences should follow the format of our recipient preference sets.

Applying tenant default preferences

When executing a workflow trigger, passing in a corresponding tenant will automatically load the default preferences for the tenant when executing the workflow. The rules for applying preferences are as follows:

• When the tenant has a preference default set, all recipients of the workflow trigger will receive the tenant default preferences when executing the workflow
• If there are tenant-specific preferences set for the user those preferences will also be evaluated (with the recipient’s per-tenant preferences taking precedence over the tenant default)
• If there is no preference default set on the tenant, then the recipient-tenant preferences will be used
• If there is no preference default set on the tenant AND the recipient has no per-tenant preferences set, then the recipient’s default preferences will be applied

To apply tenant default preferences for a workflow run, pass a tenant through to your workflow trigger:

Retrieving preferences with tenant defaults applied

When getting a preference set for a recipient, it's also possible to pass a tenant parameter that will return the recipient's preference set with any tenant default preferences applied.

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.