Tenant preferences

Learn how to enable your customer admins to set default preferences for users in their tenant.
✨
Enterprise plan feature. Tenant preference defaults are only available on our Enterprise plan.

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.

🚨
Terminology callout. This guide assumes you know about tenants in Knock and what they do. If you're new to tenants, we recommend reading our concept guide on tenants before continuing.

Overview

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

  1. Enable your tenant admins to create a default PreferenceSet for their tenant.
  2. Enable your users to override that tenant default PreferenceSet with their own preferences.
  3. 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 PreferenceSet.

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.

🚨
Terminology clarification. You'll encounter "default" in a few places in the Knock preferences model:
  1. At the environment-level when you set your default PreferenceSet for all users.
  2. At the tenant-level when you set the default PreferenceSet for all users in a tenant.
  3. At the user-level when you set a user's PreferenceSet without providing a tenant 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.

  • 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 override the tenant-level default preferences.
  • 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.
←Overview
Object preferences→