Identity Verification

Identity verification lets you securely identify logged-in users in the Eloquent chat widget. When a user is authenticated on your website, you can pass Eloquent a signed JWT so the agent knows who the user is and can provide a more personalized support experience.

In Eloquent, identity verification is handled through the identify integration. Your server creates a signed JWT, your frontend passes that token to the Eloquent widget, and Eloquent verifies the token before linking the conversation to an agent profile.

When to Use Identity Verification

Personalize the Chat Experience

Use identity verification when you want the agent to recognize logged-in users and respond with user-specific context.

• Greet users by name or account details
• Understand the user's subscription, role, or plan
• Provide support based on verified profile information
• Attach conversations to the same known user over time

Use Verified User Context

The verified JWT claims are added as system context for the agent. This allows the agent to use trusted identity information while answering the user.

• User ID (required)
• Email address (recommended)
• Name
• Plan or subscription tier
• Any other custom claims you include in the JWT

Keep Agent Profiles Up to Date

Each valid identity token creates or updates an Eloquent agent profile for the provided user_id. This means user information can stay current without manually updating the profile elsewhere.

Implementation Guide

Prerequisites

• The Eloquent embed script is installed on your website.
• The identify feature is enabled for your company or agent.
• You have access to the agent integration settings in the Eloquent dashboard.

Get Your JWT Secret

1. Open the Eloquent dashboard.
2. Select the agent you want to configure.
3. Go to Integrations -> Identity Verification.
4. Generate a JWT secret.
5. Store the secret securely on your server, for example in an environment variable.

The JWT secret is only shown when it is generated. Keep it private and never expose it in frontend code.

JWT Identity Verification

JWT Overview

Eloquent uses a JSON Web Token to verify that the current website visitor is a real authenticated user from your own application. The JWT is signed on your server with the secret from the Eloquent dashboard.

When Eloquent receives the token, it verifies the signature using the configured secret. If the token is valid, Eloquent creates or updates the agent profile for that user and attaches the verified identity to the chat request.

JWT Payload

The JWT payload must include a user_id.

Required claims:

• user_id: a stable unique identifier for the user in your system

Optional claims:

• email: the user's email address (recommended)
• name: the user's name
• plan: the user's plan or subscription tier
• role: the user's role in your application
• Any other custom attributes you want to make available to the agent

Eloquent stores email directly on the agent profile when provided. Other custom claims are stored as profile claims.

Generate the JWT on Your Server

JWTs must be generated server-side. Do not generate them in the browser, because that would expose your Eloquent JWT secret.

import jwt from "jsonwebtoken";
const secret = process.env.ELOQUENT_JWT_SECRET;
const token = jwt.sign(
  {
    user_id: user.id,
    email: user.email,
    name: user.name,
    plan: user.plan,
    role: user.role,
  },
  secret,
  {
    expiresIn: "1h",
    algorithm: "HS256",
  }
);

Return the Token to Your Frontend

Your application should expose an authenticated endpoint that returns a token for the currently logged-in user.

app.post("/api/eloquent-token", async (req, res) => {
  const user = await getCurrentUser(req);
  if (!user) {
    return res.status(401).json({
      message: "Unauthorized",
    });
  }
  const token = jwt.sign(
    {
      user_id: user.id,
      email: user.email,
      name: user.name,
      plan: user.plan,
    },
    process.env.ELOQUENT_JWT_SECRET,
    {
      expiresIn: "1h",
      algorithm: "HS256",
    }
  );
  return res.json({ token });
});

Identify the User in the Frontend

After your frontend receives the signed JWT, pass it to the Eloquent widget using window.eloquent("identify", { token }).

async function identifyEloquentUser() {
    const response = await fetch("/api/eloquent-token", {
      method: "POST",
      credentials: "include",
    });
    if (!response.ok) {
      return;
    }
    const data = await response.json();
    window.eloquent("identify", {
      token: data.token,
    });
  }
  identifyEloquentUser();
}

Call identify after the Eloquent embed script has loaded and before the user starts a chat when possible.

Complete Example

Step 1: User Logs In

Authenticate the user with your existing login flow. After login, your backend can create an Eloquent identity token for that user.

app.post("/api/login", async (req, res) => {
  const { email, password } = req.body;
  const user = await authenticateUser(email, password);
  if (!user) {
    return res.status(401).json({
      message: "Invalid credentials",
    });
  }
  const token = jwt.sign(
    {
      user_id: user.id,
      email: user.email,
      name: user.name,
      plan: user.plan,
      support_tier: user.supportTier,
    },
    process.env.ELOQUENT_JWT_SECRET,
    {
      expiresIn: "1h",
      algorithm: "HS256",
    }
  );
  return res.json({
    user: {
      id: user.id,
      email: user.email,
      name: user.name,
    },
    eloquentToken: token,
  });
});

Step 2: Pass the Token to Eloquent

async function loginUser() {
  const response = await fetch("/api/login", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    credentials: "include",
    body: JSON.stringify({
      email: "[email protected]",
      password: "password",
    }),
  });
  if (!response.ok) {
    return;
  }
  const data = await response.json();
  window.eloquent("identify", {
    token: data.eloquentToken,
  });
}

Step 3: Eloquent Verifies the User

When the user sends a chat message, Eloquent includes the identity token in the chat request. The backend verifies the JWT using the configured secret.

If the token is valid, Eloquent will:

• Create or update the agent profile for the provided user_id
• Store the email claim when provided
• Store additional claims as profile claims
• Attach the profile to the conversation
• Add the verified identity data as system context for the agent

Security Best Practices

• Generate JWTs on your server only.
• Store the Eloquent JWT secret in an environment variable.
• Never expose the JWT secret in frontend JavaScript.
• Use short-lived tokens, for example 1h.
• Use a stable internal user ID for user_id.
• Avoid using emails as user_id, because emails can change.
• Only include claims that are useful for support or personalization.
• Do not include passwords, payment details, access tokens, or other highly sensitive data.

Behavior Notes

• The token must be signed with HS256.
• The JWT must contain user_id.
• The email claim is optional.
• Additional claims are supported.
• Invalid, expired, or missing tokens are ignored for identity purposes.
• Standard JWT timing claims such as iat, exp, and nbf are not stored as profile claims.

Troubleshooting

User Is Not Identified

• Check that the agent has a JWT secret configured.
• Confirm the frontend calls window.eloquent("identify", { token }).
• Confirm the token is sent before or during the chat session.

JWT Verification Fails

• Confirm the token is signed with HS256.
• Confirm the server uses the same secret that was generated in Eloquent.
• Confirm the token has not expired.
• Confirm the JWT payload contains a string user_id.

Profile Data Is Missing

• Confirm the JWT contains the claims you expect.
• Use email for the profile email field.
• Use additional top-level JWT claims for custom profile claims.
• Remember that iat, exp, and nbf are not stored as profile claims.