Web Chat Identity Verification

Pass verified user identity from your website to the Convrs Web Chat widget using JSON Web Tokens (JWTs). This allows agents, chatbots, and AI to know exactly who they are talking to — without relying on the user to identify themselves.

When the chat widget runs on an authenticated page (such as a customer portal, banking dashboard, or account area), your backend already knows who the user is. JWT identity verification lets you securely pass that information to Convrs so it can be used throughout the conversation.

What this enables:

• Agents see verified customer details (name, account number, CRM link) without asking
• Chatbots can personalize responses and access user-specific data in flow logic
• AI has richer context for generating relevant answers
• Returning users are automatically reconnected to their chat history, even across devices or after clearing cookies

What is a JWT?

A JSON Web Token (JWT) is an industry-standard method for securely transmitting information between two systems. It is widely used by platforms such as Stripe, Auth0, Intercom, and Zendesk for identity verification.

How JWT Works

A JWT is a short string of text that contains a set of claims (data about the user) and a cryptographic signature that proves the data has not been tampered with.

A JWT has three parts separated by dots: header.payload.signature

• Header — identifies the token type and signing algorithm (always HS256 for Convrs)
• Payload — contains the user data (name, email, account number, etc.)
• Signature — a cryptographic hash that verifies the token was created by your server using your secret key

The token is generated by your backend server using a shared secret key that only your server and Convrs know. The user's browser carries the token but cannot read, modify, or forge it. When Convrs receives the token, it verifies the signature to confirm the data is authentic and has not been altered.

Setup Overview

Setting up JWT identity verification involves three steps: generating a signing secret in Convrs, creating tokens on your backend, and adding a single line of JavaScript to your page.

Step 1 — Generate a Signing Secret

Create a signing secret in the Convrs administration panel. This secret is shared between your backend and Convrs.

Steps:

1. Navigate to Administration > Organization Settings > Developer - WebChat.
2. Click Generate Secret.
3. Copy the secret and store it securely on your server (e.g. in an environment variable). This is the only time the full secret is shown.

Step 2 — Generate a JWT on Your Backend

When a user logs into your site, generate a JWT containing their identity information. This should be done server-side, never in the browser.

Use an established JWT library for your programming language. We recommend:

• Node.js — jsonwebtoken (maintained by Auth0)
• Python — PyJWT
• PHP — firebase/php-jwt
• Java — io.jsonwebtoken / jjwt
• Ruby — ruby-jwt

Node.js example:

const jwt = require('jsonwebtoken');

const token = jwt.sign(
  {
    userId: 'user-12345',
    email: 'jane@example.com',
    name: 'Jane Doe',
  },
  process.env.CONVRS_SIGNING_SECRET,
  { algorithm: 'HS256', expiresIn: '1h' }
);

Python example:

import jwt, time, os

token = jwt.encode(
    {
        "userId": "user-12345",
        "email": "jane@example.com",
        "name": "Jane Doe",
        "exp": int(time.time()) + 3600,
    },
    os.environ["CONVRS_SIGNING_SECRET"],
    algorithm="HS256",
)

Step 3 — Add the Token to Your Page

Pass the token to the chat widget by setting a global JavaScript variable on your page. This can appear anywhere — before or after the widget script tag.

Steps:

1. Set a global JavaScript variable called ConvrsUser containing the token string. Output this from your backend template into a script tag anywhere on the page.

<!-- Your existing Convrs webchat embed -->
<script defer id="convrs-webchat"
  src="https://webchat.conv.rs/YOUR_WIDGET_ID.js">
</script>

<!-- Add this anywhere on the page -->
<script>var ConvrsUser = "eyJhbGciOi...";</script>

The widget reads ConvrsUser when it opens the WebSocket connection. If the variable is not set, the widget operates normally without identity verification.

JWT Payload Fields

The JWT payload contains the data you want to pass to Convrs. Fields are divided into identity fields, automation data, and agent display data.

Identity Fields

These fields identify the user and update their contact record in Convrs.

User Data (userData)

The userData object passes custom data that is available to chatbot flows and logic blocks. This allows your chatbot to personalize responses and make decisions based on information from your system — without needing API calls during the conversation.

{
  "userData": {
    "accountNumber": "AC-12345",
    "plan": "enterprise",
    "vipTier": "gold",
    "companyName": "Acme Corporation",
    "activeSince": "2023-01-15"
  }
}

userData is a freeform key-value object — you control the keys and values. There is no fixed schema. Values can be strings, numbers, or booleans.

How it works with flows:

• Data is stored on the user's record and merged with any existing userData (top-level keys are updated; keys not present in the JWT are left unchanged)
• In the Flow Builder, access values using logic blocks with the syntax {{userData.accountNumber}}
• Use conditions like userData.plan == "enterprise" to branch conversation flows
• The data is available immediately — no API calls or integrations required

Agent Display Data (agentData)

The agentData array defines information displayed to agents in the user panel during a live chat. Unlike userData (which is for chatbot automation), agentData is specifically designed for human agents and supports rich formatting.

Each item in the array is an object with a label (what the agent sees as the field name) and a value (the data). Items are displayed in the order they appear in the array, giving you full control over the layout.

{
  "agentData": [
    { "label": "Account",      "value": "AC-12345" },
    { "label": "Plan",         "value": "Enterprise", "type": "status", "color": "info" },
    { "label": "VIP Tier",     "value": "Gold",       "type": "status", "color": "warning" },
    { "label": "Verified",     "value": true,         "type": "boolean" },
    { "label": "Member Since", "value": "2024-03-15", "type": "date" },
    { "label": "Last Login",   "value": "2026-04-23T14:30:00Z", "type": "datetime" },
    { "label": "Balance",      "value": 1250.00,      "type": "currency", "currency": "USD" },
    { "label": "Points",       "value": 48750,        "type": "number" },
    { "label": "Email",        "value": "jane@example.com", "type": "email" },
    { "label": "Mobile",       "value": "+447700900123",     "type": "phone" },
    { "label": "CRM Record",   "value": "https://crm.example.com/12345", "type": "link", "text": "View in CRM" }
  ]
}

Agents see this data in a Visitor Details card in the user panel, with a lock icon indicating the data has been verified and can be trusted.

Supported Display Types

The type field controls how the value is formatted for the agent. If omitted, the value is displayed as plain text.

Full Example

A complete example showing all available fields in a single JWT payload.

Complete JWT Payload

This example includes identity fields, automation data, and agent display data.

{
  "userId": "user-12345",
  "email": "jane@example.com",
  "name": "Jane Doe",
  "phone": "+447700900123",
  "locale": "en-GB",
  "crmID": "CRM-56789",

  "userData": {
    "accountNumber": "AC-12345",
    "plan": "enterprise",
    "vipTier": "gold"
  },

  "agentData": [
    { "label": "Account",      "value": "AC-12345" },
    { "label": "Plan",         "value": "Enterprise", "type": "status", "color": "info" },
    { "label": "VIP Tier",     "value": "Gold",       "type": "status", "color": "warning" },
    { "label": "Verified",     "value": true,         "type": "boolean" },
    { "label": "Balance",      "value": 1250.00,      "type": "currency", "currency": "USD" },
    { "label": "CRM Record",   "value": "https://crm.example.com/12345", "type": "link", "text": "View in CRM" }
  ]
}

Node.js — generating and outputting the token:

// Server-side (e.g. Express route handler)
const jwt = require('jsonwebtoken');

app.get('/dashboard', (req, res) => {
  const user = req.session.user; // your authenticated user

  const convrsToken = jwt.sign(
    {
      userId: user.id,
      email: user.email,
      name: user.fullName,
      userData: {
        accountNumber: user.accountNumber,
        plan: user.plan,
      },
      agentData: [
        { label: 'Account', value: user.accountNumber },
        { label: 'Plan',    value: user.plan, type: 'status', color: 'info' },
      ],
    },
    process.env.CONVRS_SIGNING_SECRET,
    { algorithm: 'HS256', expiresIn: '1h' }
  );

  res.render('dashboard', { convrsToken });
});

HTML template output:

<script>var ConvrsUser = "{{convrsToken}}";</script>
<script defer id="convrs-webchat"
  src="https://webchat.conv.rs/YOUR_WIDGET_ID.js">
</script>

Best Practices

Follow these recommendations for a secure and reliable integration.

Security

Recommendations for keeping your integration secure.

• Always use HS256 — this is the only signing algorithm accepted by Convrs
• Set an expiry — use expiresIn: '1h' (or the exp claim) to limit the token's lifetime
• Generate tokens server-side only — never expose the signing secret in client-side code
• Store the secret securely — use environment variables, not configuration files committed to source control
• Rotate secrets if compromised — use the Rotate Secret feature in the Developer - WebChat panel, which provides a 48-hour grace period for the previous secret
• Do not cache pages with tokens — set Cache-Control: private to prevent CDNs from serving one user's token to another

Token Lifecycle

How to manage token generation and refresh.

• Generate once at login — create the token when the user authenticates and store it in the server-side session
• Reuse across page loads — output the same token on each page within its lifetime, rather than generating a new one per page
• Refresh before expiry — if using a single-page application, regenerate the token at 75% of its lifetime (e.g. after 45 minutes for a 1-hour token)
• For SPAs and static sites — expose a /api/chat-token endpoint that returns a fresh token, and call it when the page loads

Testing

Use the built-in token verification tool to test your integration before going live.

Steps:

1. Navigate to Administration > Organization Settings > Developer - WebChat.
2. Paste your JWT token into the Test a JWT Token field.
3. Click Verify Token.
4. If valid, you will see the decoded payload with all the fields. If invalid, you will see the specific error (expired, invalid signature, etc.).

Related Topics

• Web Widget
• Organization Settings
• Convrs Web Chat API
• Chatbot Flows
• Logic Blocks