Tenant preferences

Docs

Platform

Preferences

Tenant preferences

Learn how to enable your customer admins to set default preferences for users in their tenant.

You can use tenant preferences to enable your customers' admins to create a tenant-specific default PreferencesSet for users in their tenant.

If you're a B2B application or a multi-tenant SaaS product, you can use tenant preferences to allow your customers to set default preferences for their users. For example, in Slack, your notification preferences are set per Slack workspace (that is, per-tenant), not as global preferences that apply across all of your Slack workspaces.

Overview

Here is how tenant preferences work and the steps you'll take to implement them:

Enable your tenant admins to create a default PreferenceSet for their tenant.
Enable your users to override that tenant default PreferenceSet with their own preferences.
Trigger your workflows with a tenant parameter to apply tenant-specific preferences.

Create a per-tenant default `PreferenceSet`

You set the default PreferenceSet for a tenant via the API by calling the tenants.set method. The preferences should follow the format of a recipient PreferenceSetRequest.

Updating the per-tenant default `PreferenceSet`

You can update the per-tenant default PreferenceSet by calling the tenants.set method with the same tenant_id and the updated preferences that you'd like to set.

The default behavior for this action is to merge the new preferences with any existing preferences. This means that any existing preferences will only have their values updated but not removed. See the frequently asked questions section below for more information on how you can use a "replace" strategy to overwrite existing preferences instead.

Set a per-tenant user `PreferenceSet`

A PreferenceSet has an id. When you set a given user's preferences in Knock, you'll use the default ID to apply the preferences universally for the user. When using one of our SDKs, the default preference set is used if you don't provide an id.

To set per-tenant preferences for a recipient, you'll use the ID of the tenant that they should be associated with as the PreferenceSet's ID.

You can also get a user's tenant-specific preferences.

Trigger per-tenant workflows

When you trigger a workflow run, you pass a tenant parameter to tell Knock which tenant in your application the workflow is executing for.

The Knock workflow engine uses that tenant parameter to evaluate the user's PreferenceSet. If the user has a tenant-specific preference set, Knock uses that to determine whether to send the notification. If the user does not have a tenant-specific preference set, Knock uses the tenant's default preference set.

Tenant preference evaluation rules

Here are a few things to keep in mind when using tenant preferences. You can learn more about how preferences are merged and evaluated here.

When executing a workflow trigger, passing in a tenant will automatically load that tenant's default PreferencesSet (if one exists) for all recipients of the workflow. These tenant-level defaults will override a recipient's own default preferences.
If the recipient has any per-tenant preferences set for that tenant.id, they will take precedence over the tenant-level default preferences. For more information on how to override a recipient's per-tenant preferences to respect the tenant-level default preferences, see the frequently asked questions below.
If there is no default PreferenceSet on the tenant AND the recipient has no per-tenant preferences set, the recipient’s default id PreferenceSet will be used. As always, the recipient's default preferences are merged with the environment-level preference defaults.

Frequently asked questions

Yes. You can do this by setting the __persistence_strategy__ key on your PreferenceSet to "replace" when calling the tenants.set method. This will overwrite any existing preferences with the new preferences provided.

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

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:

A visual of the tenant's default preferences merging into the recipient's tenant-specific preferences with the replace strategy applied

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:

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.
The __strategy__ key can only be used on a combined workflows-channel_types or categories-channel_types preference, as seen in the example above.
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.