Preferences overview

The following standard hierarchy is used to merge preferences when no tenant is applied to the workflow trigger. Each item in the list takes precedence over the ones that follow it:

1. A recipient's default preference set
2. The environment-level default preference set

Let's take a look at an example to visualize this merge. Suppose that you have the following preference sets:

To visualize the resulting merged preferences, we'll start at the bottom of the hierarchy and work our way up, adding any preferences from the environment default preference set that are not already present in the recipient's default preference set. Any preferences that are set in both places will keep the value from the recipient's default preference set:

The resulting merged preferences will look like this:

The environment-level setting to opt all users into collaboration notifications will be respected because the recipient doesn't have an explicit preference for that category, but the recipient's preference to specifically opt in to SMS messages will override the environment-level setting to opt out.

The following hierarchy is used to merge preferences when a tenant is applied to the workflow trigger. Each item in the list takes precedence over the ones that follow it:

1. A recipient's tenant-specific preference set
2. The tenant's default preference set
3. The environment-level default preference set

This merge works in the same way as the standard merge above, but it evaluates different preference sets. Let's take a look at an example to visualize this merge. Suppose that you have the following preference sets:

To visualize the resulting merged preferences, we'll start at the bottom of the hierarchy and move upward—first adding preferences from the environment default to the tenant's default preference set, then adding any of those preferences that are not already present in the recipient's tenant-specific preference set. At each step, if a preference exists in both sets, the value from the higher level in the hierarchy takes precedence:

The resulting merged preferences will look like this:

The environment-level settings to opt all users out of SMS messages and into collaboration notifications will be respected because neither the tenant nor the recipient have an explicit preference for these items. The tenant's preference to opt users in to reminders notifications will be overridden by the recipient's setting to opt out.

• If you do not set a preference for a given channel, workflow, or workflow category, Knock defaults them to true.
• When a recipient clicks an unsubscribe link, their default preference set will be updated, marking commercial_subscribed as false. They will be opted-out of commercial messages, and they will continue to receive transactional messages based on their other preferences. Read more about commercial unsubscribe here.

Knock only sends a notification if all preference combinations that exist on the recipient evaluate to true.

• A workflow can belong to multiple categories. Only one of those category preferences needs to evaluate to false for the notification not to send.
• If a workflow's category is set to false, the notification will not send even if a channel_type or channel on the workflow is explicitly set to true.
• Channel preferences take precedence over channel type preferences. If a specific channel is set to true but the channel_type is set to false, the notification will still send through that specific channel.
• If both channel and channel_type preferences exist for the same notification, the channel preference is evaluated first and takes priority.

Our Preferences API provides endpoints for retrieving all of the preferences that have been set on a recipient.

You can also use the workflow debugger in your dashboard to view the preferences that were evaluated for the recipient on a given workflow run.

Yes. While our preferences API endpoints will default to overwriting the existing PreferenceSet with the new preferences provided, it's possible to update a single preference using either of the two options below.

1. Setting a __persistence_strategy__ key on your PreferenceSet to "merge"

You can provide an optional __persistence_strategy__ key when providing your PreferenceSet to our preferences API endpoints. Setting this key to "merge" will perform a deep merge of the provided preferences into any existing preferences.

Here's what this looks like in practice. If a user has these existing default preferences:

and they would like to update their email preference for the collaboration category to false, you can do so by providing the following PreferenceSet to our user preferences endpoint:

This will result in the following PreferenceSet being set on the recipient:

2. Inline identifying preferences

You can update a single preference inline by using any of our recipient identification methods, including while triggering a workflow (as seen in the example below). This will perform a deep merge of the provided preferences into any existing preferences, just like any other properties stored on the recipient.

Note that the syntax for providing the id of the preference set on an InlinePreferenceSetRequest is slightly different than the way that our preferences endpoints handles them; you'll simply provide a key-value pair where the key is the id of the preference set and the value is the PreferenceSet you'd like to merge.

Here's what this looks like in practice. If a user has these existing default preferences:

and they would like to update their email preference for the collaboration category to false, you can do so by providing the following InlinePreferenceSetRequest while triggering a workflow:

This will result in the following PreferenceSet being set on the recipient prior to the workflow being triggered:

By default, a recipient's individual preferences will always take the highest precedence in the merge when preferences are evaluated (according to the hierarchy outlined under Merging preferences above).

Some applications have use cases where it's necessary for a preference that is set at the tenant level to override a user's individual preference. For example, you may want to allow a team admin to disable a certain type of notification for their entire team, regardless of whether an individual user has opted in to that notification. To achieve this, you can set the __strategy__ key on the preference you'd like to override to a value of "replace".

In the following example, although the user has specifically opted into receiving email notifications for the collaboration category, email notifications with that category will not send because the tenant's default preference set has set the collaboration category to false. Consider the following preference sets:

The merge during preference evaluation will look like this:

The recipient's preference for the project-updates category is preserved in the merge, but their preference for collaboration notifications is overridden by the tenant's preference due to the replace strategy.

This replace strategy will also be reflected when you request the user's preferences via API. Although the user's tenant-specific preferences have explicitly been set to the above, the __strategy__ key will be present on the PreferenceSet returned, indicating that their preference has been overridden by the tenant's:

You can also use the replace strategy to override top-level channel_types or channels preferences:

Here are some important thing to keep in mind when using the replace strategy:

• This strategy will only apply to the specific preference(s) where it's included; there's no way to override the entire PreferenceSet at the top level.
• When the preference with the replace strategy is removed, any existing preferences that were overridden by the replace strategy will be immediately restored to their original values. For the example above, the user will once again be opted in to collaboration notifications.

Setting preferences on a tenant has the default behavior of merging the new preferences with any existing preferences. This means that once a preference has been set with the replace strategy, simply omitting the __strategy__ from your next request will not remove it.

There are two ways to remove it from the preference set:

• Explicitly set the __strategy__ key to "merge" for the preference(s) that should no longer override the user's preferences. This is the default behavior (a user's tenant-specific preferences will take precedence over the tenant's own default).
• Use the __persistence_strategy__ key on your request to replace the entire preference set rather than merging your new preferences with the existing ones. See the FAQ here for more information.

In the workflow debugger, Knock will show you the preferences that were evaluated for the recipient on a given workflow run. You may notice channel_types preferences, even if you didn't explicitly set them on the recipient or in your environment default preference set.

This is because Knock automatically opts all recipients in to all channel_types by default, to ensure that the recipient receives notifications unless they have been explicitly opted out.

If you want to override this behavior, you can set the channel_types preference to false for all channel types in your environment default preference set. This will opt the recipient out from all notifications.

Channel preferences and channel type preferences work together to provide different levels of granularity:

• Channel type preferences (channel_types) control broad categories like email, sms, or push
• Channel preferences (channels) control specific channel instances using their UUID identifiers

Channel preferences always take precedence over channel type preferences. This allows users to:

• Opt out of all email notifications but still receive critical transactional emails from a specific channel
• Opt into SMS notifications generally but exclude marketing messages from a particular provider
• Have fine-grained control over their notification experience

For example, if a user has:

They will not receive email notifications in general, but will still receive notifications sent through the specific channel with ID 550e8400-e29b-41d4-a716-446655440000.