Identifying Shoppers

You can tell the widget who the current shopper is, using either of two trust levels that work independently.

Identify

Tell Remark the shopper’s email, phone, or name.

Verify

Verify the shopper’s identity with a signed token or one time passcode.

You can operate at both trust levels through window.remark(...), which loads asynchronously. Your code needs to wait until it’s ready before calling it. The examples below do that with the whenRemarkReady helper from Waiting for Remark to initialize. Remark can also verify shoppers without any code on your site, once your Remark representative turns it on. When a shopper needs to prove who they are, the widget can email them a one-time passcode and verify them once they enter it. See Verify with an email passcode.

Identify (unverified)

Use identify to tell Remark who the shopper might be, so it can greet them by name or attach the conversation to a known shopper.

whenRemarkReady(() => {
  window.remark('identify', {
    email: 'shopper@example.com',
    phone: '+1 415 555 0132',
    firstName: 'Sam',
    acceptsMarketing: true
  });
});

Fields

Field	Type	Description
`email`	string	The shopper’s email address.
`phone`	string	The shopper’s phone number. Any common format works. Remark normalizes it.
`firstName`	string	The shopper’s first name, used to greet them.
`acceptsMarketing`	boolean	Whether the shopper has opted in to marketing.

Every field is optional, but provide at least an email or phone for the shopper to count as identified. If you’ve connected Klaviyo, Remark also identifies shoppers who arrive with Klaviyo’s __kla_id cookie. It records the email, first name, and phone from their Klaviyo profile the same way identify does, without verifying them.

Because identify details come from the browser, anyone could claim any email. Use them for personalization only, not to gate order history, account details, or other sensitive data. Verify the shopper with an email passcode or a token for that.

Verify with an email passcode

Remark can verify a shopper on its own, without any integration code needed on your site. When a shopper asks about something that needs a verified identity, such as their order history, the widget asks for their email address and emails them a one-time passcode. Once the shopper enters the code, Remark treats that email as verified. The whole flow happens inside the chat widget:

The shopper shares or confirms their email address.
Remark emails them a one-time passcode.
The shopper enters the code in the widget.

While waiting, the shopper can resend the code, change the email address, or skip verification. Codes are 6 digits long, expire after 10 minutes, and allow 5 attempts. An email verified this way stays verified for 30 days. Because the shopper has proven they control the inbox, Remark trusts the email the same way it trusts a token you sign yourself (see Verify with a token). Both routes end in the same verified state. Once verified, Remark links the shopper to the orders and purchase history associated with that email, so agents and experts can look up past orders and help with post-purchase questions. On Shopify, order lookup, order cancellation, address changes, and customer lookup accept a verified email without also asking for a last name. Email passcodes need no code on your site, but they’re off by default because Remark sends the email on your behalf. Ask your Remark representative to turn them on. They work in the chat widget, alongside identify and verify: if you already verify signed-in shoppers with a token, they won’t be asked for a code, and shoppers who aren’t signed in to your site can still verify themselves when they need to.

Verify with a token

A signed token proves a shopper is who they say they are, so Remark can show order history, account details, or act on their behalf. Use it when shoppers sign in to your site, so they are verified as soon as the page loads and never need to enter an emailed passcode. Your server creates a short, signed token naming the shopper, and Remark checks the signature before it trusts the token. The one rule is to keep that signing secret on your server and out of the browser: as long as it stays there, no one can forge a token. Remark holds its own copy so it can check the signature.

1. Get your signing secret

In the Remark dashboard, go to Settings → Identity verification and select Generate secret. Remark shows it only once, so copy it and store it somewhere only your server can read, such as an environment variable, and never in client-side code. To replace a secret later, use Regenerate. The new secret works right away, and any token signed with the old one stops working, so regenerate when traffic is low.

2. Sign a token on your server

When you render a page for a signed-in shopper, create a short-lived JSON Web Token signed with that secret. The token must:

use the HS256 algorithm,
include the shopper’s email, phone, or both,
set sub to the shopper’s lead, so the token only works for that shopper’s session,
set an expiry (exp) no more than 5 minutes after Remark receives the token. Remark allows 60 seconds of clock difference and rejects tokens that expire later than that.

// Node.js, in your token endpoint. This runs on your server, never in the browser.
import jwt from 'jsonwebtoken';

// Remark sets the shopper's lead in the `remark_lead` cookie on your domain, so
// it arrives with this request. Bind the token to it.
const lead = req.cookies.remark_lead;

const token = jwt.sign(
  { email: 'shopper@example.com' }, // and/or phone, from your server-side session
  process.env.REMARK_IDENTITY_SECRET,
  { algorithm: 'HS256', subject: lead, expiresIn: '5m' }
);

The sub claim (subject above) is what ties the token to one shopper. Remark gives every visitor a lead and stores it in the remark_lead cookie on your domain, so it rides along with the request above. If your token endpoint can’t read that cookie, read the lead in the browser from localStorage under remark_lead and send it to your server. Unlike the email and phone, the lead is not sensitive, so reading it from the browser is fine: it only scopes the token to this session.

Build the token for the shopper who is signed in to your server. Read their email or phone from your server-side session, never from a query parameter, form field, or anything else the browser sends. Otherwise someone could request a token that claims to be another shopper.

3. Verify from the page

Fetch a fresh token from your server when the page loads, then pass it to Remark:

async function verifyShopper() {
  const { token } = await fetch('/api/remark-identity-token').then((r) => r.json());
  window.remark('verify', token);
}

whenRemarkReady(verifyShopper);

Sign a fresh token on each page load rather than storing one and reusing it. On pages that stay open past the token’s exp, such as single-page apps, call verify again with a fresh token before it expires.

Confirming it worked

If the token checks out, Remark records the shopper’s email and phone as verified until the token’s exp. If a token is invalid, expired, or set to last too long, Remark rejects it. The page doesn’t get an error back, and nothing prints to the browser console unless the request itself fails. To confirm your tokens are being accepted, open Settings → Identity verification in the dashboard. The signing secret shows when it was last used: after a verified shopper loads a page, the badge changes from Never used to Used and the date.

Signing out

When the shopper signs out of your site, tell Remark to drop their verified status:

window.remark('unverify');

Call this from your sign-out handler. It works whether or not the shopper ever verified, so you don’t have to track that yourself. The shopper’s email and phone stay on file as unverified details, and verification from an email passcode ends too.

Token reference

Claim	Required	Description
`email`	one of `email` / `phone`	The verified email address.
`phone`	one of `email` / `phone`	The verified phone number.
`sub`	yes	The shopper’s lead, from the `remark_lead` cookie. Binds the token to one session so a leaked token can’t be reused against another shopper.
`exp`	yes	Expiry, in Unix seconds. No more than 5 minutes after Remark receives the token, with 60 seconds of clock tolerance. Verified status ends at this time.

Remark normalizes the email and phone, so send real, well-formed values.

Getting Started

Guides

Dashboard

API

Integrations

Identify

Verify

Identify (unverified)

Fields

Verify with an email passcode

Verify with a token

1. Get your signing secret

2. Sign a token on your server

3. Verify from the page

Confirming it worked

Signing out

Token reference

Identify

Verify

​Identify (unverified)

​Fields

​Verify with an email passcode

​Verify with a token

​1. Get your signing secret

​2. Sign a token on your server

​3. Verify from the page

​Confirming it worked

​Signing out

​Token reference

Identify (unverified)

Fields

Verify with an email passcode

Verify with a token

1. Get your signing secret

2. Sign a token on your server

3. Verify from the page

Confirming it worked

Signing out

Token reference