Authentication

​

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
  },
});

If you want to provide an email address for the customer, you can do so by passing an email property in the customerDetails object. We will only accept email addresses that have been verified.

In order to know that the email address that you provide has been verified, we require an emailHash, which is a hash of the email address and a secret.

This emailHash can be either manually provided by you or you can use our built-in email verification process to do it for you. Both methods are described below.

​

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

If your chat widget is embedded within an authenticated application (e.g. behind a login), you already know the user’s identity. In this case, you can directly match the authenticated user to their Plain customer record:

1. Generate a secret in the Chat settings page on Plain
2. Calculate the email hash in 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. Finally, pass both the email and email hash when initializing the Plain widget:

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',
  },
});

​

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

If your chat widget is publicly accessible (e.g., on your marketing website), you should use Plain’s built-in customer verification system. This ensures that customers can prove their identity through email verification.

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

Plain.init({
  requireAuthentication: true
});

When enabled:

1. New customers will need to provide their email address
2. They’ll receive a verification code via email
3. After verification, they can start chatting