Hosted preference center

Docs

Platform

Preferences

Learn how to use Knock's hosted preference center to enable your users to manage notification preferences without writing any code.

Knock's hosted preference center is a page where your users manage their default notification preferences. You configure it from the dashboard; Knock hosts and renders the page, so you can launch a preference center without building or hosting any UI yourself.

This is the fastest way to let your users update their preferences when they receive a notification. If you need more control over the experience, you can build your own preference center UI on top of Knock's preferences API.

How it works

Knock hosts the preference center at p.knock.app. Each user accesses their own preferences through a signed link that looks like this:

The token identifies the recipient, so users don't need to log in to your product to view or update their preferences.

When a user opens the link, they see their preference settings based on the configuration in your dashboard, with your account branding, preference options, and the ability to opt out of commercial messaging.

When the user clicks Save preferences, Knock writes their changes back to their default preference set. The link never expires.

Configure your preference center

You configure the preference center from the Knock dashboard under Platform > Preferences > Preference center. Your configuration is environment-specific.

When the preference center is saved and enabled, changes go live in the environment right away. When the preference center is disabled, users can only edit their commercial messages opt-out preference.

Show the account name

Toggle Show account name to display your account name alongside your logo at the top of the page.

Set the title and body

Set the title and body copy that appear at the top of the page. Use these to tell your users what the page does, for example "Notification preferences" and "Manage your preferred notification channels and categories."

Add preference options

Each preference option is a row that your users can toggle. For each row, you configure:

Type. Map the row to a category, a workflow, or a channel. For categories and workflows you can select an existing key or create a new one.
Display name and description. The label your users see for this row, for example "Comments and replies," and an optional line of supporting text shown beneath it.
Channel types. For category or workflow rows, limit the row to specific channel types, such as email, in-app, push, or SMS. When you select one or more channel types, the row renders a toggle per channel type so users can opt in or out of each one. This doesn't apply to channel rows, which already map to a single channel type.

Configure commercial messages

The commercial messages row gives your users a single place to opt out of promotional or non-essential notifications. This is backed by the same commercial_subscribed preference used for commercial unsubscribe, so opting out here also satisfies one-click CAN-SPAM requirements for your commercial messaging.

The commercial messages row is mandatory and always renders in the preference center, whether the preference center is enabled or disabled. You can change the title and body copy for the row, but you can't remove it.

Set your branding

The preference center uses the branding configured for your account, including your logo, icon, and primary color. See branding for more on how branding works in Knock.

Preview as a user

Before you save, you can preview the preference center as a specific user. This renders that user's page exactly as they would see it with their current preferences and your latest configuration, so you can confirm the experience before it goes live.

Enable the preference center

Toggle Enabled to turn the preference center on for the environment.

How configuration maps to preferences

Each row in your preference center maps to a key in the recipient's PreferenceSet. A row can point at a category, a workflow, or a channel, and can scope to one or more channel types.

When a user saves their preferences, Knock updates the corresponding keys on the recipient's default preference set. These changes are merged with any environment or tenant defaults during preference evaluation, with the recipient's preferences taking precedence according to the merge hierarchy.

Linking to the preference center

To link a user directly to their preference center from a notification, include the URL in your message template or email layout using the built-in variable:

Knock renders the user-specific link in the notification. Use vars.manage_preferences_url when you want to give users full control over their preferences via the hosted preference center. For single-click opt-out of commercial messages via the commercial unsubscribe feature, use vars.commercial_unsubscribe_url instead.

Copying configuration between environments

Your preference center configuration is environment-specific, just like your preference defaults. You can copy it from one environment to another using the "Copy to..." button in the upper right corner of the preference center settings. This enables you to keep your environments in sync as you move from development to production.

Learn more

To learn more about the preferences model behind the preference center, see the preferences overview.