Identity Verification

Identity verification lets your agent know exactly who it’s talking to. When a logged-in user opens the chat popup, you pass their identity as a signed token so the agent can give personalized, trusted responses.

Identity verification works with the chat popup only — it relies on the widget’s JavaScript API and is not available in the iframe embed.

The identity verification section showing the widget key and code snippets

Why use it

Personalized responses — the agent can greet users by name and reference their account details.
Security — prevents users from impersonating others in chat.
Better records — conversations are tied to a verified identity, not just an anonymous session.

How it works

You sign a token on your backend with your agent’s widget key, then pass that token to the widget in the browser.

Copy your widget key

On the agent’s Connect page, find the Identity verification section and copy the widget key.

Sign a token on your backend

Generate a signed JWT for each logged-in user. Include their ID, name, and any metadata you want the agent to know:

const jwt = require('jsonwebtoken');

const token = jwt.sign(
  {
    userId: current_user.id,           // required
    userName: current_user.name,       // required — display name for the agent
    userMetadata: {                    // optional — any key-value pairs
      email: current_user.email,
      plan: current_user.plan,
      company: current_user.company,
    }
  },
  process.env.CONVOTOOL_WIDGET_KEY,    // your agent's widget key
  { algorithm: 'HS256', expiresIn: '24h' }
);

Identify the user in the browser

Pass the token to the widget, and clear it when the user logs out:

window.convotool('identify', { token });

// On logout:
window.convotool('resetUser');

Never expose your widget key in client-side code. Sign the JWT on your backend and pass only the token to the browser.

When to use it

Identity verification is optional. Use it when your site has user accounts and you want personalized chat, when you need to tie conversations to a verified user, or when you want to prevent anonymous abuse. If your site has no accounts, you can skip it — your agent works for anonymous visitors too.

Next: Visibility & rate limiting

Control who can use your agent and cap message volume.

Getting Started

Build Your Agent

Knowledge Base

Deploy Your Agent

Conversations

Analytics & Outcomes

Tools & Integrations

Team & Organization

Billing

Account

Identity Verification

Why use it

How it works

When to use it

Next: Visibility & rate limiting

​Why use it

​How it works

​When to use it

Next: Visibility & rate limiting

Why use it

How it works

When to use it