User identification

User identification lets you securely pass user information to the chat widget. This enables personalized conversations, linking chats to your user records, and showing user context to your support team.

How it works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Your backend   │     │  Your frontend  │     │    Replyful     │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         │  1. Generate token    │                       │
         │<──────────────────────│                       │
         │                       │                       │
         │  2. Return signed JWT │                       │
         │──────────────────────>│                       │
         │                       │                       │
         │                       │  3. replyful.identify │
         │                       │──────────────────────>│
         │                       │                       │
         │                       │  4. Verify & link     │
         │                       │<──────────────────────│

Your frontend requests a token from your backend
Your backend generates a short-lived JWT signed with your chatbot’s secret
Your frontend passes the token to the widget
Replyful verifies the token and links the conversation to the user

Get your chatbot secret

Each chatbot has its own signing secrets.

Go to your Replyful dashboard
Navigate to Settings → Developers → Secrets
Create a secret for your chatbot and copy it

A chatbot can have several active secrets at once, so you can rotate: create the new one, switch your backend to it, then archive the old one.

Keep the secret on your server. Never expose it in client-side code.

Breaking change: tokens must include an exp (expiry) claim. Replyful rejects tokens without one, and the widget fires identity-failed. A token without an expiry never stops working, so anyone who copies one could sign in as that user for good.

Generate a token on your backend

Create an API endpoint that generates a signed JWT for authenticated users.

Node.js
PHP

Install the jsonwebtoken package:

npm install jsonwebtoken

Create a token endpoint:

import jwt from 'jsonwebtoken';

const REPLYFUL_SECRET = process.env.REPLYFUL_CHATBOT_SECRET;

function generateReplyfulToken(user) {
  return jwt.sign(
    {
      // Required
      userId: user.id,

      // Optional. Only send an email address you have verified.
      email: user.emailVerified ? user.email : undefined,
      name: user.name,
    },
    REPLYFUL_SECRET,
    {
      expiresIn: '1h', // Required: sets the exp claim
      algorithm: 'HS256'
    }
  );
}

// Express example
app.get('/api/replyful-token', authenticate, (req, res) => {
  const token = generateReplyfulToken(req.user);
  res.json({ token });
});

Install the firebase/php-jwt package:

composer require firebase/php-jwt

Create a token endpoint:

<?php
use Firebase\JWT\JWT;

$replyfulSecret = getenv('REPLYFUL_CHATBOT_SECRET');

function generateReplyfulToken($user) {
    global $replyfulSecret;

    $payload = [
        'userId' => $user->id,        // Required
        'name' => $user->name,        // Optional
        'exp' => time() + 3600        // Required: 1 hour expiration
    ];
    // Optional. Only send an email address you have verified.
    if ($user->emailVerified) {
        $payload['email'] = $user->email;
    }

    return JWT::encode($payload, $replyfulSecret, 'HS256');
}

// API endpoint example
if ($_SERVER['REQUEST_METHOD'] === 'GET' && $_SERVER['REQUEST_URI'] === '/api/replyful-token') {
    // Ensure user is authenticated
    $user = getCurrentUser();
    if (!$user) {
        http_response_code(401);
        exit;
    }

    header('Content-Type: application/json');
    echo json_encode(['token' => generateReplyfulToken($user)]);
}

Call identify from your frontend

After a user logs in, fetch the token from your backend and pass it to the widget:

async function identifyUser() {
  const response = await fetch('/api/replyful-token', {
    credentials: 'include'
  });
  const { token } = await response.json();

  replyful('identify', { token });
}

// Call after user logs in
identifyUser();

You can call identify before the widget has loaded; it’s applied once the chat is ready. Once loaded, identify returns a Promise that resolves to the result instead of throwing:

Result	Meaning
`{ verified: true, transferred }`	The user is linked. `transferred` is present when the visitor’s earlier anonymous chat moved to this user: `{ conversations, messages }`, as counts
`{ verified: false }`	The token was rejected, for example because it expired or was signed with the wrong secret. The visitor stays anonymous

To act on the result, wait for the chat to be ready:

replyful('on', 'ready', async () => {
  const { token } = await fetch('/api/replyful-token').then((r) => r.json());
  const { verified } = await replyful('identify', { token });
});

The same outcomes also fire as the identity-verified and identity-failed events. See the JavaScript API.

React example

import { useEffect } from 'react';
import { useUser } from './auth';

function ReplyfulIdentify() {
  const { user, isAuthenticated } = useUser();

  useEffect(() => {
    if (!isAuthenticated) return;

    async function identify() {
      const res = await fetch('/api/replyful-token');
      const { token } = await res.json();
      window.replyful?.('identify', { token });
    }

    identify();
  }, [isAuthenticated, user?.id]);

  return null;
}

Require identification

By default, visitors can chat before they are identified. If your chatbot should only serve signed-in users, for example inside your product, you can make identification mandatory:

In your Replyful dashboard, open Channels → Chat and pick your chatbot.
Open the Embed tab and turn on Require identification.

The message box then stays locked until identify succeeds, and Replyful refuses messages to the AI agent from visitors who haven’t been identified. This applies everywhere the chatbot is installed, so only turn it on when every page that shows it calls identify. Use a separate chatbot for pages with anonymous visitors.

Token payload

Field	Type	Required	Description
`userId`	string	Yes	Unique identifier in your system
`exp`	number	Yes	Expiry as a Unix timestamp in seconds. Most JWT libraries set it from an option such as `expiresIn`
`email`	string	No	An email address you have verified belongs to this user
`name`	string	No	User’s display name

Replyful treats a signed email as proven. It can link the visitor to an existing contact with that address, and the AI agent can use it to look up their data through your API tools. Leave it out if your sign-up flow doesn’t confirm the address. Without a signed email, Replyful has no address to send replies to when the visitor asks for a human, and a signed-in visitor can’t type one in. A typed address is unproven, and attaching it to a verified user would let anyone claim someone else’s inbox. If you want email follow-ups for signed-in users, include their verified email in the token. Other claims are ignored and not stored.

Security best practices

Never expose your chatbot secret in client-side code
Generate tokens server-side only to prevent tampering
Always set an expiration, and keep it short (1 hour recommended)
Only sign email addresses you have verified
Authenticate users before generating tokens
Use HTTPS for all API requests

The widget handles missing or invalid tokens gracefully — users can still chat anonymously.

Getting started

Email

Chat

Knowledge

Reporting

User identification

How it works

Get your chatbot secret

Generate a token on your backend

Call identify from your frontend

React example

Require identification

Token payload

Security best practices

​How it works

​Get your chatbot secret

​Generate a token on your backend

​Call identify from your frontend

​React example

​Require identification

​Token payload

​Security best practices

How it works

Get your chatbot secret

Generate a token on your backend

Call identify from your frontend

React example

Require identification

Token payload

Security best practices