Skip to content
Documentation
Embeddable Widget
User Identification

User Identification

If your application already knows who the visitor is (e.g., they’re logged into your SaaS product), you can pass their identity to the widget using an encrypted token. This skips lead capture and links conversations to a known Contact.

How It Works

  1. Enable the Browser External channel — an identity secret (AES-256-GCM key) is automatically generated
  2. Copy the secret from the channel configuration page
  3. On your server, encrypt a JSON payload containing the user’s identity:
{"id": "unique_user_id", "name": "Optional Name", "email": "optional@email.com"}
  1. Pass the encrypted blob via data-user-token on the script tag
  2. The widget sends this token with every API request
  3. TeamWeb AI decrypts it and links the conversation to a Contact record via the id field

The id field is required. name and email are optional but will be stored on the Contact if provided.

Encryption Examples

Python:

import base64, json, os
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

secret = base64.b64decode("your-base64-secret-from-teamwebai")
payload = json.dumps({"id": "user_123", "name": "Alice"}).encode()
nonce = os.urandom(12)
ct = AESGCM(secret).encrypt(nonce, payload, None)
token = base64.b64encode(nonce + ct).decode()

Node.js:

const crypto = require('crypto');

const secret = Buffer.from('your-base64-secret-from-teamwebai', 'base64');
const payload = JSON.stringify({ id: 'user_123', name: 'Alice' });
const nonce = crypto.randomBytes(12);
const cipher = crypto.createCipheriv('aes-256-gcm', secret, nonce);
const ct = Buffer.concat([cipher.update(payload, 'utf8'), cipher.final()]);
const tag = cipher.getAuthTag();
const token = Buffer.concat([nonce, ct, tag]).toString('base64');

Using the Token

Add the encrypted token to the widget’s script tag:

<script src="https://your-teamwebai-domain/static/js/chat-widget.js"
        data-assistant-id="123"
        data-user-token="BASE64_ENCRYPTED_TOKEN"></script>

When a valid token is provided:

  • Lead capture is automatically skipped
  • The visitor is identified immediately
  • Conversations are linked to the Contact record matching the id field
  • If the Contact doesn’t exist yet, one is created with the provided name and email