---
title: "Preferences overview"
description: "Learn how to implement notification preferences in Knock."
tags: ["recipients", "conditions", "prefs", "preferences"]
section: Preferences
---

[Preferences](/api-reference/recipients/preferences) enable your users to opt-out of the notifications you send using Knock.

## How preferences work

A user has a <a href="/api-reference/recipients/preferences">`PreferenceSet`</a>. A `PreferenceSet` is a JSON object that tells Knock which channels, categories, and/or workflows a user has opted out of receiving.

When Knock runs a workflow for a user, we evaluate their `PreferenceSet`. A message will not send if the user has opted out of receiving it.

A preference set is built using four keys: `categories`, `channels`, `channel_types`, `workflows`. These keys resolve to boolean values to determine if a user has opted out of receiving a notification.

A recipient's `default` preference set also has a `commercial_subscribed` key which determines if the recipient should receive notifications sent by commercial workflows or broadcasts. Read more about commercial unsubscribe [here](/preferences/commercial-unsubscribe).

A few examples:

```json title="Unsubscribe user from admin category notifications"
{
  "categories": { "admin": false }
}
```

<br/>
```json title="Unsubscribe user from email notifications"
{
  "channel_types": { "email": false }
}
```

<br/>
```json title="Unsubscribe user from a specific email channel"
{
  "channels": { "550e8400-e29b-41d4-a716-446655440000": false }
}
```
<br/>
```json title="Unsubscribe user from at-mention notifications"
{
  "workflows": { "mention": false }
}
```

## Channels vs. channel types

Channel preferences provide more granular control than channel types by allowing you to specify preferences for individual channels rather than entire channel types.

- **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 because they are more specific. See [preference evaluation rules](#preference-evaluation-rules) below for more information.

You can combine these keys to create preference grids like the one in the image below:

```json title="A preference grid for categories and channels"
{
  "categories": {
    "collaboration": {
      "channel_types": {
        "email": true,
        "in_app_feed": true
      },
      "channels": {
        "550e8400-e29b-41d4-a716-446655440000": false,
        "6ba7b810-9dad-11d1-80b4-00c04fd430c8": true
      }
    },
    "project-updates": {
      "channel_types": {
        "email": false,
        "in_app_feed": true
      }
    }
  },
  "workflows": {
    "invoice-issued": {
      "channel_types": {
        "email": true
      },
      "channels": {
        "6ba7b810-9dad-11d1-80b4-00c04fd430c8": true,
        "f47ac10b-58cc-4372-a567-0e02b2c3d479": false
      }
    }
  }
}
```

The `PreferenceSet` above models this preference grid in your application:

<Image
  src="/images/what-is-knock/preferences.png"
  alt="An image of a preference set"
  width={1356}
  height={1452}
  className="rounded-md mx-auto border border-gray-200"
/>

<Callout
  emoji="👩‍💻"
  title="See an example."
  text={
    <>
      Check out{" "}
      <a
        href="https://in-app-demo.knock.app/preferences"
        target="_blank"
        rel="noopener"
      >
        our interactive example app
      </a>{" "}
      to see how making changes to the preference center UI updates the values
      of a&nbsp;
      <code>PreferenceSet</code>
    </>
  }
/>

## Environment-level default preferences

You can set an [environment](/version-control/environments)-level default `PreferenceSet` that applies to all recipients in an environment, either in the Knock dashboard or with the [Management API](/mapi-reference/environments/defaults/update). When Knock evaluates preferences for a recipient who has not set any preferences of their own, the environment default serves as the baseline. This is useful when you want to establish a baseline that differs from Knock's default of opting all recipients in to all notifications.

The environment-level default is always the lowest priority in the [merge hierarchy](#merging-preferences). Any preferences set at the recipient or tenant level will take precedence over it.

To set up an environment-level default preference set, see [Create a default preference set](/preferences/custom-preference-center#create-environment-level-default-preferences).

## Merging preferences

When a default `PreferenceSet` exists for an environment or tenant, Knock will merge all applicable preferences for a recipient when evaluating whether or not to send a notification. Any preferences set at the recipient level will take precedence in the merge, according to the hierarchy outlined below.

### Merge hierarchy

The following hierarchies are used when merging preferences.

{/* Note: The original diagrams for the merge hierarchy images can be found in Figma here: https://www.figma.com/board/LlFCmkX4jgGDRcfJuTqkhl/Preferences-diagrams */}

<AccordionGroup>
  <Accordion title="Standard preference merge hierarchy" anchorSlug="standard-preference-merge-hierarchy">
    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](/preferences/overview#how-preferences-work) set
    2. The [environment-level default preference](/preferences/custom-preference-center#create-environment-level-default-preferences) set

    Let's take a look at an example to visualize this merge. Suppose that you have the following preference sets:
    <Image
      src="/images/concepts/preferences/standard-prefs-start.png"
      alt="A visual of the environment default and recipient default preference sets prior to merging"
      width={400}
      height={900}
      className="rounded-md mx-auto border border-gray-200"
    />
    <br />

    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:

    <Image
      src="/images/concepts/preferences/standard-prefs-merge.png"
      alt="A visual of the environment default preferences merging into the recipient's default preferences"
      width={400}
      height={1004}
      className="rounded-md mx-auto border border-gray-200"
    />
    <br />

    The resulting merged preferences will look like this:

    <Image
      src="/images/concepts/preferences/standard-prefs-result.png"
      alt="A visual of the combined environment default and recipient default preference sets after merging"
      width={400}
      height={498}
      className="rounded-md mx-auto border border-gray-200"
    />
    <br />
    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.

  </Accordion>
  <Accordion title="Tenant-specific preference merge hierarchy" anchorSlug="tenant-specific-preference-merge-hierarchy">
    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](/multi-tenancy/per-tenant-preferences) set
    2. The [tenant's default preference](/multi-tenancy/per-tenant-preferences#create-a-per-tenant-default-preferenceset) set
    3. The [environment-level default preference](/preferences/custom-preference-center#create-environment-level-default-preferences) 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:

    <Image
      src="/images/concepts/preferences/tenant-prefs-start.png"
      alt="A visual of the tenant-specific preference sets prior to merging"
      width={400}
      height={1004}
      className="rounded-md mx-auto border border-gray-200"
    />
    <br />
    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:

    <Image
      src="/images/concepts/preferences/tenant-prefs-merge.png"
      alt="A visual of the tenant-specific preferences merging into the tenant's default preferences"
      width={400}
      height={1004}
      className="rounded-md mx-auto border border-gray-200"
    />
    <br />

    The resulting merged preferences will look like this:

    <Image
      src="/images/concepts/preferences/tenant-prefs-result.png"
      alt="A visual of the combined tenant-specific and tenant default preference sets after merging"
      width={400}
      height={498}
      className="rounded-md mx-auto border border-gray-200"
    />
    <br />
    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.


    <Callout

type="info"
title="Note:"
text={

<>
  If a <code>tenant</code> is applied to the workflow trigger but there are no
  tenant-specific preferences set on the tenant or the recipient, the
  recipient's <code>default</code> preference set will be evaluated according to
  the standard merge hierarchy, as if no <code>tenant</code> were applied.
</>
} />

  </Accordion>
</AccordionGroup>

The `commercial_subscribed` preference is an exception to both hierarchies above. When it's set on a recipient's `default` preference set, it always takes precedence over tenant and environment defaults. This keeps a user's commercial opt-out with them across every tenant they belong to.

For more information on how you can override these hierarchies, see the [frequently asked questions](#frequently-asked-questions) section below.

## Preference evaluation rules

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:

<AccordionGroup>
  <Accordion title="General preference rules" anchorSlug="general-preference-rules">
    - 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](/preferences/commercial-unsubscribe).
  </Accordion>
  <Accordion title="Resolving preference conflicts" anchorSlug="resolving-preference-conflicts">
    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.

  </Accordion>
  <Accordion title="Debugging preferences" anchorSlug="debugging-preferences">
    Our [Preferences API](/api-reference/recipients/preferences) provides endpoints for retrieving all of the preferences that have been set on a recipient.

    You can also use the [workflow debugger](/send-notifications/debugging-workflows) in your dashboard to view the preferences that were evaluated for the recipient on a given workflow run.

    <Image
      src="/images/concepts/preferences/workflow-preferences-evaluation.png"
      alt="An image of a workflow run's evaluated preferences"
      width={500}
      height={381}
      className="mx-auto rounded-md border border-gray-200"
    />

  </Accordion>
</AccordionGroup>

## Going live with preferences

Once you've configured your preference model, you need a way for users to manage their preferences. Knock offers two approaches:

- **Hosted preference center.** Knock hosts and renders a preference page for each user, accessible via a signed URL. You configure rows, labels, and branding in the dashboard - no code required. Supports the user's `default` preference set only. See [hosted preference center](/preferences/hosted-preference-center) for more information.
- **Custom preference center.** You build the UI and embed it in your product, using Knock's preferences API to read and write preference values. This gives you full control over layout, UX, and which preferences you surface—including [per-tenant](/multi-tenancy/per-tenant-preferences) and [object](/preferences/object-preferences) preferences. You can optionally use the dashboard-managed configuration to drive your row definitions without hardcoding them. See [custom preference center](/preferences/custom-preference-center) for more information.

## Bulk set user preferences

You can update the preferences of up to 1000 users in a single batch by using the `users.bulkSetPreferences` method. This executes an asynchronous job which will overwrite any existing preferences for the users provided. You can track the progress of the `BulkOperation` returned via the [bulk operation API](/api-reference/overview/bulk-endpoints).

<MultiLangCodeBlock
  title="Bulk set preferences for many users"
  snippet="users.bulkSetPreferences"
/>

<br />

## Advanced concepts

- [Per-tenant preferences](/multi-tenancy/per-tenant-preferences). In multi-tenant B2B applications, an advanced use case is customer admins who want to set the tenant-level default `PreferenceSet` for new users within their tenant.
- [Object preferences](/preferences/object-preferences). You can set preferences for object recipients, just as you can for users.
- [Preference conditions](/preferences/preference-conditions). You can build advanced conditions and store them on Knock’s preference model to power use cases such as per-resource muting (example: mute notifications about this task) or threshold alerts (example: only notify me if my account balance is below $5).
- Merge strategy. It's possible to configure the merge strategy on specific preferences within a `PreferenceSet`. This allows you to override the default merge hierarchy when preferences are evaluated. See the [frequently asked questions](#frequently-asked-questions) section below for more details and use cases.
- Workflow overrides. If you need to override a recipient's notification preferences to send notifications like a password reset email, you can override the preferences model. 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.
- [Commercial unsubscribe](/preferences/commercial-unsubscribe). You can configure 1-click unsubscribe links to help users opt-out of commercial or promotional notifications and comply with CAN-SPAM requirements.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I update a single preference rather than replacing a recipient's entire preference set?" anchorSlug="faq-update-single-preference">
    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:
    ```json title="An existing default preference set"
    {
      "categories": {
        "collaboration": {
          "channel_types": {
            "email": true,
            "in_app_feed": true
          }
        }
      }
    }
    ```
    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](/api-reference/users/set_preferences):

    ```javascript title="Updating a single preference using the Node SDK"
    import Knock from '@knocklabs/node';

    const client = new Knock({
      apiKey: 'My API Key',
    });

    const preferenceSet = await client.users.setPreferences('user_id', 'default', {
      __persistence_strategy__: 'merge',
      categories: {
        collaboration: {
          channel_types: {
            email: false
          }
        }
      }
    });
    ```

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

    ```json title="The resulting default preference set"
    {
      "categories": {
        "collaboration": {
          "channel_types": {
            "email": false,
            "in_app_feed": true
          }
        }
      }
    }
    ```
    <br />

    <>
    **2. Inline identifying preferences**
    </>
    You can update a single preference inline by using any of our [recipient identification
    methods](/managing-recipients/identifying-recipients), 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](/concepts/users#storing-user-properties).

    Note that the syntax for providing the `id` of the preference set on an [`InlinePreferenceSetRequest`](/api-reference/recipients/preferences/schemas/inline_preference_set_request)
    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:
    ```json title="An existing default preference set"
    {
      "categories": {
        "collaboration": {
          "channel_types": {
            "email": true,
            "in_app_feed": true
          }
        }
      }
    }
    ```
    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:
    ```javascript title="Triggering a workflow with inline preferences using the Node SDK"
    import Knock from "@knocklabs/node";
    const knock = new Knock({ apiKey: process.env.KNOCK_API_KEY });

    await knock.workflows.trigger("new-comment", {
      data: { project_name: "My Project" },
      recipients: [
        {
          id: "1",
          preferences: {
            default: {
              categories: {
                collaboration: {
                  channel_types: {
                    email: false
                  }
                }
              }
            }
          }
        },
      ],
    });
    ```
    This will result in the following `PreferenceSet` being set on the recipient prior to the workflow being triggered:
    ```json title="The resulting default preference set"
    {
      "categories": {
        "collaboration": {
          "channel_types": {
            "email": false,
            "in_app_feed": true
          }
        }
      }
    }
    ```

  </Accordion>
  <Accordion title="What is the merge strategy, and how can I use it to override the merge hierarchy?" anchorSlug="faq-preference-merge-strategy">
    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](#merging-preferences) above).
    
    Some applications have use cases where it's necessary for a [preference that is set at the tenant level](/multi-tenancy/per-tenant-preferences#set-a-per-tenant-user-preferenceset) 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:

    ```json title="A user's tenant-specific preference set"
    {
      "categories": {
        "collaboration": {
          "channel_types": {
            "email": true
          }
        },
        "project-updates": {
          "channel_types": {
            "email": true
          }
        }
      }
    }
    ```

    ```json title="The tenant's default preference set"
    {
      "categories": {
        "collaboration": {
          "__strategy__": "replace",
          "channel_types": {
            "email": false
          }
        },
        "project-updates": {
          "channel_types": {
            "email": false
          }
        }
      }
    }
    ```
    <br />
    The merge during preference evaluation will look like this:

    {/* Note: The original diagram for this image can be found in Figma here: https://www.figma.com/board/LlFCmkX4jgGDRcfJuTqkhl/Preferences-diagrams */}
    <Image
      src="/images/concepts/preferences/replace-prefs-merge.png"
      alt="A visual of the tenant's default preferences merging into the recipient's tenant-specific preferences with the replace strategy applied"
      width={400}
      height={1004}
      className="rounded-md mx-auto border border-gray-200"
    />
    <br />
    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:

    ```json title="The returned user preference set"
    {
      "categories": {
        "collaboration": {
          "__strategy__": "replace",
          "channel_types": {
            "email": false
          }
        },
        "project-updates": {
          "channel_types": {
            "email": true
          }
        }
      }
    }
    ```
    <br />
    You can also use the `replace` strategy to override top-level `channel_types` or `channels` preferences:

    ```json title="Tenant default preference set with top-level channel_types override"
    {
      "channel_types": {
        "__strategy__": "replace",
        "email": false,
        "sms": true
      }
    }
    ```
    <br />
    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.

    #### Removing the `replace` strategy

        Setting preferences on a tenant has [the default behavior](/multi-tenancy/per-tenant-preferences#updating-the-per-tenant-default-preferenceset) 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](/multi-tenancy/per-tenant-preferences#frequently-asked-questions) for more information.

  </Accordion>
  <Accordion title="Why do I see 'channel types' preferences in the workflow debugger even though I didn't set them?" anchorSlug="faq-channel-type-preferences-in-debugger">
    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.

    <Image
      src="/images/concepts/preferences/workflow-preferences-evaluation.png"
      alt="An image of a workflow run's evaluated preferences"
      width={500}
      height={381}
      className="mx-auto rounded-md border border-gray-200"
    />
    <br />
    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.

  </Accordion>
  <Accordion title="What's the difference between channel preferences and channel type preferences?" anchorSlug="faq-channel-vs-channel-type-preferences">
    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:
    ```json
    {
      "channel_types": { "email": false },
      "channels": { "550e8400-e29b-41d4-a716-446655440000": true }
    }
    ```
    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`.

  </Accordion>
</AccordionGroup>
