Authenticate chat customers

The chat widget treats a customer as anonymous until you prove who they are. Pick one of 3 approaches:

Display fields: show a name and avatar for an anonymous customer
Signature: sign a signed-in customer’s email and identifiers on your server
Email verification: ask the customer to verify an email in the widget

Pass display fields

A customer is anonymous until you provide and prove an email. You can still pass display fields on customerDetails in Plain.init. Plain doesn’t treat those fields as proof of who the customer is:

Plain.init({
  customerDetails: {
    fullName: 'Ada Lovelace',
    shortName: 'Ada',
    chatAvatarUrl: 'https://example.com/avatars/ada.png',
  },
});

Sign a known customer

Use this when the customer is already signed in to your product and you know their email. The signature covers the email, plus externalId and tenantIdentifier when you send them. externalId is your ID for the customer. tenantIdentifier is { tenantId: 'ten_0123456789' } or { externalId: 'acme' } for their account.

Generate a chat secret

Go to Settings → Chat, open the chat app, and click Generate secret. Keep the secret on your server, never in the browser. Clicking Re-generate secret invalidates the current secret, and signatures from the old secret stop verifying.

Build the signature on your server

The signature is a Hash-based Message Authentication Code (HMAC). Sign the message with HMAC-SHA256 and your chat secret, then hex-encode the digest.With no externalId and no tenantIdentifier, the message is the email itself:

ada@example.com

With either identifier, the message is JSON. Sort the keys alphabetically at every level, and set v to the number 1:

{"email":"ada@example.com","identifiers":{"externalId":"user_123","tenantIdentifier":{"externalId":"acme"}},"v":1}

This TypeScript example builds that message and returns the signature. JSON.stringify drops identifiers you leave undefined and keeps the key order shown:

import { createHmac } from 'node:crypto';

type TenantIdentifier = { tenantId: string } | { externalId: string };

function customerDetailsSignature(args: {
  secret: string;
  email: string;
  externalId?: string;
  tenantIdentifier?: TenantIdentifier;
}): string {
  const { secret, email, externalId, tenantIdentifier } = args;
  const message =
    externalId === undefined && tenantIdentifier === undefined
      ? email
      : JSON.stringify({
          email,
          identifiers: { externalId, tenantIdentifier },
          v: 1,
        });
  return createHmac('sha256', secret).update(message).digest('hex');
}

Test vectors

Compare your function to these signatures. Each one uses the secret chat_secret_example. Each block shows the exact message, then its lowercase hex signature. A space or line break in the message changes the signature.Sign ada@example.com with no identifiers:

message: ada@example.com
signature: ad990bba2bd71e79e79c042c6291344ae152fa267d6c15446b2e97b2892834df

Sign ada@example.com and externalId user_123:

message: {"email":"ada@example.com","identifiers":{"externalId":"user_123"},"v":1}
signature: 07c1924d9865df9b1cefceedebd61dfd1b2b25ac790389ea56e5eb005fce660d

Sign ada@example.com and tenantIdentifier { externalId: 'acme' }:

message: {"email":"ada@example.com","identifiers":{"tenantIdentifier":{"externalId":"acme"}},"v":1}
signature: d5932983b7a19f4f167407c3b47977be3f0558289a964ab1fc1160dadd4aa0dc

Sign ada@example.com and tenantIdentifier { tenantId: 'ten_0123456789' }:

message: {"email":"ada@example.com","identifiers":{"tenantIdentifier":{"tenantId":"ten_0123456789"}},"v":1}
signature: 7441bdf9502fd332a92e7b657c5908c44e9602c40ad650692313d82f4f55c0fa

Sign ada@example.com, externalId user_123, and tenantIdentifier { externalId: 'acme' }:

message: {"email":"ada@example.com","identifiers":{"externalId":"user_123","tenantIdentifier":{"externalId":"acme"}},"v":1}
signature: bd90fca5ec85587de6f5e92f097720477f1648bd42d3983c27c17bea3df2eb66

Pass the details and signature to the widget

Pass customerDetailsSignature next to customerDetails. The values in customerDetails must match the ones you signed. In this example, fetchCustomerFromBackend calls your own endpoint, which returns { customerDetails, customerDetailsSignature } for the signed-in customer, so the details and the signature come from one place.

const { customerDetails, customerDetailsSignature } =
  await fetchCustomerFromBackend();

Plain.init({
  customerDetails,
  customerDetailsSignature,
});

Fetch a new payload when the email or the identifiers change. Plain rejects the request when externalId or tenantIdentifier differs from what you signed.

The signature is a bearer credential: anyone who has it can claim that customer.

Verify an unknown email

Set requireAuthentication when the customer isn’t signed in and you want an email before they can chat. This fits a public page where you don’t manage sign-in. You can pair this option with the Require email verification setting in Settings → Chat.

Plain.init({
  requireAuthentication: true,
});

The widget asks for an email address. Plain emails a one-time code. After the customer enters the code, they can start a thread.

Agents

Channels

Platform

Integrations

Workflows

Broadcasts

Help center

Security

Plans & Billing

Authenticate chat customers

Pass display fields

Sign a known customer

Verify an unknown email

​Pass display fields

​Sign a known customer

​Verify an unknown email

Pass display fields

Sign a known customer

Verify an unknown email