Hosted preference center

Docs

Platform

Preferences

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

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

This is the fastest way to give your users a preference center. If you need more control over the experience, you can still 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 environment-level preference center configuration shape. When the user clicks Save preferences, Knock writes their changes back to the recipient's default preference set.

The page reflects the recipient it was generated for, including the account branding, the preference options you've configured, and a row for commercial messages.

Enable and configure your preference center

You configure the preference center from the Knock dashboard under Platform > Preferences > Preference center. Your configuration is environment-specific, and saving it puts the changes live in that environment right away.

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 or a workflow. You can select an existing key or create a new one.
Display name. The label your users see for this row, for example "Comments and replies."
Description. An optional line of supporting text shown beneath the display name.
Channel types. 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.

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, primary color, and font. You can update these under Settings > Branding. 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 loads that user's literal preference center, rendering the 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.

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 or a workflow, 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 users to the preference center

To send users to their preference center, include the manage-preferences URL in your email templates using the built-in variable:

This sits alongside the existing vars.commercial_unsubscribe_url variable, which links to the one-click commercial unsubscribe flow. Use vars.manage_preferences_url when you want to give users full control over their preferences, and vars.commercial_unsubscribe_url for a single-click opt-out of commercial messages.

You can also add the preference center link to your emails without editing template code by configuring footer links in your email layout settings.

Copying configuration between environments

Your preference center configuration is environment-specific, just like your preference defaults. You can copy the configuration from one environment to another 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. To set up one-click unsubscribe for commercial messaging, see commercial unsubscribe.