Comms preference deep links

Link a customer from an email or SMS straight into their Profile Portal comms preferences, optionally changing one preference on the way in, and choose between the profile-ID and ID-token mechanisms.

Profile Portal’s messaging page can be opened for a specific customer without a login, and can apply one communication preference change as it loads. This is what makes one-tap “manage your preferences” and category toggles in campaign email possible. It is also what makes the link dangerous in the wrong place: it acts on load, and anyone holding the URL can use it.

Two ways to link into preferences

	Profile-ID parameters	ID-token link
URL	`https://[portal]/messaging?p={profileId}` plus optional change parameters	`https://[portal]/account?token={{ event.IDToken }}` on any portal route
Authentication	None. The profile ID is the only credential.	A short-lived, profile-scoped Omneo ID token that opens an authenticated session
Changes a preference on load	Yes, one attribute per link	No, the customer makes the change on the page
Lifetime	Evergreen	Minutes. Only for messages sent immediately after the triggering event
Where the value comes from	The Omneo profile ID synced to your comms platform as a profile property	A Klaviyo metric sent with `withToken=true`
Documented at	This page	Klaviyo metrics

Use the profile-ID parameters for evergreen footer links and for category toggles in campaign email. Use the ID-token link when the message is Flow-triggered and sent immediately, and the link leads anywhere more sensitive than a category toggle. Neither replaces your comms platform’s native unsubscribe; see Before you send.

URL contract

https://[portal]/messaging?p={profileId}&commsAttribute={field}&commsValue={1|0}

Parameter	Required	What it does
`p`	Yes	The Omneo profile ID. Missing or unknown IDs render an error state.
`commsAttribute`	No	The comms field to change, for example `email_promo`. For a custom comms attribute, this is the option value to add to or remove from the attribute’s array.
`commsValue`	No	`1` to turn on, `0` to turn off. Send the digits, not `true` or `false`.
`isCustom`	No	`true` when `commsAttribute` is an option of a custom comms attribute.
`type`	No	Read only when `isCustom=true`. The handle of the custom comms attribute the option belongs to, for example `interests`. The namespace is always `comms`.

p on its own opens the preference centre and changes nothing. That is the safe default for a footer link.

What happens on load

When the change parameters are present, the page applies the change to the profile, shows a confirmation, then renders the full preferences form so the customer can adjust anything else. One attribute is processed per request; a campaign that needs two changes needs two links, or the plain ?p= link. Consent timestamps (email_consent_updated_at, sms_consent_updated_at) are recorded on every change made this way, the same as a change made on the form. See Comms preferences.

Standard and custom attributes

Standard comms fields are the flags on the profile’s comms record: email_promo, sms_promo, the channel and category combinations, and the *_optout fields. For these, commsValue=1 means on and 0 means off. Custom comms attributes reached by deep link are arrays of option values. commsValue=1 adds the option in commsAttribute to the array, 0 removes it. What that means to the customer depends on how the attribute was configured for your portal:

Inclusion attributes hold what the customer wants. 1 means “send me this”.
Exclusion attributes hold what the customer does not want. 1 means “stop sending me this”.

On an exclusion attribute, commsValue=1 mutes the category. A “tell me more about X” link built the obvious way silently opts the customer out, and the confirmation still says the preference was turned on. Check how your custom attribute is configured with your Omneo account manager before building a single custom-attribute link.

Custom attributes configured as a single value (radio-button frequency pickers, for example) cannot be targeted by deep link.

The unsubscribe route

https://[portal]/unsubscribe?p={profileId}

This is a one-shot action, not a preference centre. On load it applies the unsubscribe fields configured for your portal, email_optout: true unless configured otherwise, and shows a confirmation with a link to manage notifications. Everything in Before you send applies to it.

Embedding in your comms platform

You need two things in the sending platform: your portal domain, and the Omneo profile ID on the contact record. The profile ID reaches your platform through the extension’s profile sync, under whatever property name is configured for your tenant. Not every contact has one. Contacts created by a platform-side form, an import, or a list Omneo has not touched will have no Omneo ID, and a link with an empty p renders the portal’s error state. Every embedded link needs a fallback, and for an unsubscribe link the fallback must be your platform’s own native unsubscribe.

Klaviyo example

Klaviyo exposes the synced property directly and {% unsubscribe_link %} for its native unsubscribe URL. Paste this into an HTML block; the drag-and-drop editor cannot wrap a button in a conditional.

{% if person.omneo_id %}
  <a href="https://[portal]/messaging?p={{ person.omneo_id }}&amp;commsAttribute=email_promo&amp;commsValue=0">Unsubscribe</a>
{% else %}
  <a href="{% unsubscribe_link %}">Unsubscribe</a>
{% endif %}

{% unsubscribe_link %} outputs the bare URL and belongs in an href. {% unsubscribe %} renders a complete anchor.
& is correct inside an HTML block; a plain & is correct in a button’s link field.
Substitute your mapped property name. Where it contains spaces, use person|lookup:'Omneo ID':'' in both the condition and the output.
The no-code equivalent is two blocks with display conditions on the property.

The same conditional around the plain ?p= link is the safer default for a footer “manage your preferences” call to action. Other platforms have their own template syntax and native unsubscribe tags; do not carry the Klaviyo example over unchanged.

Before you send

A deep link changes the preference in Omneo. Whether that stops the next send depends on how your comms platform is connected. With the Klaviyo extension, email_promo only drives Klaviyo subscription state when Use Email Promo for Subscriptions is enabled for your tenant; it is disabled by default. Disabled, a customer who clicks an email_promo deep link sees a confirmation and is still subscribed in Klaviyo unless your campaigns and flows filter on the synced property. Keep your platform’s native unsubscribe as the unsubscribe mechanism in the footer, and use deep links for preference-centre entry and category toggles. See Klaviyo profile sync.

The change happens on load with no confirmation step. Any tool that pre-fetches links in email, such as a security scanner, will trigger it. On an opt-out link that produces unsubscribes nobody asked for. On an opt-in link it produces a consent record, with a consent timestamp, created by a machine. Never put commsValue=1 on a consent field in an emailed link; send the customer to the plain ?p= preference centre and let them make the choice.

The link is unauthenticated. A forwarded email lets anyone change that customer’s preferences. Acceptable for interest toggles; weigh it before it drives suppression, and prefer the ID-token link where the message is sent immediately.
Gmail and Apple Mail show their own unsubscribe control from the List-Unsubscribe header your platform generates. Some unsubscribes will always land at the platform first, so make sure the platform-to-Omneo sync is live.
Check what share of your list carries an Omneo profile ID before relying on the deep link branch.

See Comms preference centre for what customers can manage and Configuring Profile Portal for the rest of the portal setup.

Omneo Insights

CX Manager

Clienteling

Profile Portal

Invites

Comms preference deep links

Comms preference deep links

Two ways to link into preferences

URL contract

What happens on load

Standard and custom attributes

The unsubscribe route

Embedding in your comms platform

Klaviyo example

Before you send

​Comms preference deep links

​Two ways to link into preferences

​URL contract

​What happens on load

​Standard and custom attributes

​The unsubscribe route

​Embedding in your comms platform

​Klaviyo example

​Before you send

Comms preference deep links

Two ways to link into preferences

URL contract

What happens on load

Standard and custom attributes

The unsubscribe route

Embedding in your comms platform

Klaviyo example

Before you send