Authentication

Authentication allow you to identify who you're talking to and personalize replies using known account context.

• Route and prioritize requests more accurately based on known customer attributes.

• Prevent duplicate customer records and avoid exposing information to the wrong person.

• Improve security while still offering a fast, seamless support experience.

Whether you're embedding chat behind a login or offering open access on your marketing site, the right authentication method ensures customers are identified correctly and securely.

Authentication options

By default, customers chatting with you will be anonymous. You can pass customer details, if you know them, in the Plain.init function call:

Plain.init({
  // ... Other options
  customerDetails: {
    fullName: 'John Doe', // Optional
    shortName: 'John', // Optional
    chatAvatarUrl: 'https://picsum.photos/32/32', // Optional
  },
});

You can also include an email address using the email field property in the CustomerDetails object. To ensure the email is verified, Plain requires an emailHash, which is a secure hash of the email address and a secret.

There are two ways to provide this hash. You can generate it yourself if the user is already authenticated in your product, or you can use Plain’s built-in email verification flow. Both methods are outlined below.

Manual email verification - when you already know the user’s identity

Use this approach when the user is logged into your application and you already know their verified email address.

If the chat widget is embedded in an authenticated environment (such as a customer dashboard), you can securely associate the session with the correct customer in Plain.

Steps

1. Generate a secret
   Head to the Chat settings page in Plain and generate a secret.

2. Calculate the email hash on your backend

import * as crypto from 'node:crypto';

const secret = '<YOUR_SECRET>';
const email = 'johndoe@example.com';
const hmac = crypto.createHmac('sha256', secret);
hmac.update(email);
const hash = hmac.digest('hex');

3. Initialize the widget with both the email and hash

const email = 'johndoe@example.com';
const emailHash = await fetchHashFromBackend(email);

Plain.init({
  customerDetails: {
    email,
    emailHash,
    // Optional: additional customer details
    fullName: 'John Doe',
    shortName: 'John',
    chatAvatarUrl: 'https://picsum.photos/32/32',
  },
});

Always calculate the email hash server-side to protect your secret.

Built-in email verification - when you don’t know the user’s identity

Use this method when you do not know who the user is and want to verify their identity before they can chat. This is ideal for public pages, such as marketing sites, or anywhere you don’t manage authentication yourself.

Plain’s built-in verification flow prompts users to verify their email before they can start chatting.

To enable this, set the requireAuthentication option to true when initializing the Plain widget:

Plain.init({
  requireAuthentication: true
});

When enabled:

• Users will be asked to enter their email address

• Plain will send them a one-time code via email

• After verification, they can start a conversation