User Verification in Live Chat

Live Chat enables user verification using JSON Web Tokens (JWT). Through JWT-based verification, users are identified as either verified or not verified within the configured live chat widget .

What is User Verification?

User verification in live chat is a process that confirms the identity of a user before they initiate a conversation. By verifying users, support teams can securely associate conversations with user accounts, personalize responses, and restrict or prioritize access to chat services. This feature also reduces spam and ensures sensitive data is only exchanged with authenticated users.

Live chat user verification is implemented using JSON Web Tokens (JWT) — a secure and compact standard for transmitting user identity information between systems.

This article covers the following topics:

• Verification key creation
• JWT generation from the verification key
• Passing the JWT to the live chat widget
• Updating the JWT token using custom JS
• JWT error logs

Create Verification Key

To create a verification key, follow these steps:

1. Log in as an admin with the Manage user verification permission.

   

2. Navigate to Agent Portal > Admin > Chat > Users and Permissions section. Then click on User Verification and select the Keys tab.

   

3. Click Create Key to begin generating a new key for a specific brand and channel, then click Generate Key to complete the process.

   

4. After adding the key, click the Copy option to copy it.

Create JWT Token using Verification Key

JWT (JSON Web Token) is a URL-safe, compact token standard (RFC 7519) used to securely transmit information between parties. Once user authentication is enabled, a valid JWT must be sent each time a user initiates a conversation through the live chat widget.Learn more about JWT.

Server-Side JWT Token Generation

For secure user verification, JWT tokens must always be generated on the server side using a private verification key. Avoid generating tokens on the client side (browser or app) to prevent exposure of sensitive signing keys, which can lead to unauthorized access or token forgery.

The rest of this article explains how to create verification keys and securely generate JWTs for use in the live chat widget.

JWT Token Structure

A JWT consists of three components:

• Header
• Payload
• Signature

Header

Defines the token type and the signing algorithm used. It includes two fields:

alg: The algorithm used to sign the token. For example, HS256 for chat.
typ: The type of token, which is JWT.

{
 "alg": "HS256",
 "typ": "JWT"
} 

Payload

Contains the claims or data you wish to transmit. Here’s an example payload with userId or email and exp (expiration time).

Note: To authenticate users in live chat widgets, the required parameters are either the userId or the email, which uniquely identifies the user.

{
 "email": "johndoe@example.com",
 "exp": 1748551800
} 

• userId (optional): A unique identifier for the user in your system. This takes precedence over email.
• email (Required): User’s email address. Either userId or email is required.
• exp (Required): Expiration time (as a Unix timestamp). The token will be invalid after this time.

Signature

Ensures the token is not altered. It is created by combining the encoded header, payload, and a shared secret using the specified algorithm. You can find your account’s shared secret under the User Authentication tab.

The final JWT token is created by combining the encoded header, payload, and signature, concatenated with periods (.).

JWT token = header.payload.signature

Node.js

How to generate the JWT token in the Node.js platform.

// bash
npm install jwt-simple

// JWT Token Generation Code
import jwt from 'jwt-simple';

// Sample payload
const payload = {
name: 'John Doe',
email: 'johndoe@example.com',
exp: Math.floor(Date.now() / 1000) + 60 * 60
};

async function generateJWT() {
return jwt.encode(payload, 'secretKey', 'HS256');
}

console.log('Generated JWT:',generateJWT());  

Python

How to generate the JWT token in the Python platform.

# bash
pip install PyJWT


# JWT Token Generation code
import jwt
import datetime

# Define your payload
payload = {
   "name": "John Doe",
   "email": "johndoe@example.com",
   "exp": datetime.datetime.utcnow() + datetime.timedelta(hours=1)
}

# Define your secret key
secret_key = "secretKey"

# Encode the JWT
def generate_jwt():
token = jwt.encode(payload, secret_key, algorithm="HS256")
return token

# If using PyJWT >= 2.0, it returns a string
print("JWT Token:\n", generate_jwt())

PHP

How to generate the JWT token in the PHP platform.

// Shell
composer require firebase/php-jwt


// Jwt Token Generation code
<?php
require 'vendor/autoload.php';

use Firebase\JWT\JWT;

function generate_jwt() {
    // Define your payload
    $payload = [
        "name" => "John Doe",
        "email" => "johndoe@example.com",
        "exp" => time() + 3600  // 1 hour expiration
    ];

    // Define your secret key
    $secret_key = "secretKey";

    // Encode the JWT
    return JWT::encode($payload, $secret_key, 'HS256');
}

echo "JWT Token:\n" . generate_jwt();

Passing the JWT Token to The Live Chat Widget

Once the JWT token is generated on your server-side, it can be used in your live chat widget configuration as shown below:

<script>
   window['boldChatSettings'] = {
   email: 'johndoe@example.com',
   userToken: 'JWTUserToken'
   }
</script>

<script src="https://example.bolddesk.com/chatwidget-api/widget/v1/<widgetId>" defer async></script>

On logout, clear the session using the clearSession method from the client API. Additionally, explicitly remove the userToken and email from the widget settings to ensure proper cleanup.

window['boldChatSettings'] = { email: '', userToken: '' } 

If the user is verified using this token, the chat module will display the verification details on the right side of the conversation.

Updating JWT Token Using Custom JS

Use a custom endpoint API in custom JS to update the user token and email. Ensure the token is refreshed before its expiration time.

function fetchToken() {
 fetch('https://your-api-endpoint.com/get-token', {
   method: 'GET',
   headers: {
     'Content-Type': 'application/json',
   }
 })
   .then(response => response.json())
   .then(data => {
     // Update the userToken in boldChatSettings with the new token
     window['boldChatSettings'].userToken = data.Token;
   });
}

// Refresh token every 25 minutes (assuming token expires in 30 minutes)
setInterval(fetchToken, 25 * 60 * 1000);

// Initial token fetch on page load
fetchToken(); 

Error Logs

Under User Verification, select the Logs tab to view all errors logged during user verification.

Sample Error Logs