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. Knock hosts and renders the page, so you can launch a preference center without building or hosting any UI yourself.

Knock hosts the page. Users access their preferences through a signed URL.
Configure in the dashboard. Set rows, labels, and branding under Platform > Preferences > Preference center.
No code required. Enable the preference center and link to it from your notifications.
User default preferences only. Does not support per-tenant, object, or non-default preference sets.

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, see Build your preference center. Not sure which approach fits? See Choosing a preference center.

How it works

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

You can also serve the preference center from your own subdomain. See Custom domain for the preference center below.

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. When a custom domain is assigned to the current environment, the preview uses that domain.

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

From workflow templates

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.

Get a signed URL from your backend

Use this when you need to generate a preference center link outside of workflow templates—for example, from your app settings page or an admin panel.

Call POST /v1/users/{user_id}/preference_center/signed_url from your backend with a secret API key. The response includes:

url. The full hosted preference center URL for the user.

Redirect the user to url. If your environment uses a custom preference center domain, the returned url reflects that domain.

See the create preference center signed URL API reference for details.

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.

Custom domain for the preference center

By default, the hosted preference center is served at p.knock.app. You can configure a custom domain to serve it from your own subdomain instead (i.e. prefs.yourcompany.com).

Once a custom domain is assigned to an environment, your templates will automatically resolve {{vars.manage_preferences_url}} variables with your custom domain.

For configuration steps, see Setting up a custom domain. Assignment changes take effect immediately.

Learn more

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