Skip to main content
Identity verification allows you to securely authenticate your users in your AI Agent widget. When an end user is logged into your website, you can identify them to your AI Agent so the widget knows who they are and can provide personalized, authenticated experiences.
Identity verification works hand-in-hand with Contacts. When an end user is identified, your AI Agent can access their Contact data to provide personalized responses and enable authenticated actions.

When to Use Identity Verification

Make your AI Agent recognize logged-in users so it can:
  • Greet users by name instead of saying “Hello there”
  • Access their account information and preferences
  • Show content relevant to their subscription or role
  • Provide support based on their history with your service
When you need actions that require specific user information from their contact record:
  • Custom actions that need to access user details (name, email, subscription info, etc.)
  • Stripe actions (billing, subscriptions, invoices) Learn more about Stripe actions.
These actions work by matching the authenticated user’s ID with a Contact record that contains their detailed information.

Implementation Guide

Prerequisites

A website with the Chatbase embed script already installed and working. New to Chatbase? Check out Your First Agent to get started with the embed script first.

1. Get Your Secret Key

Navigate to your Chatbase Dashboard to get your verification secret:
1

Open Your AI Agent

Go to Chatbase Dashboard and select your AI Agent.
2

Access Embed Settings

Navigate to Deploy → click on Manage on Chat widgetEmbed tab.
3

Copy Secret Key

Copy the verification secret key shown in the embed code section.
Chatbase embed code with identity verification secret

2. Generate End User Hash on Your Server

Security Critical: End user hashes must be generated on your server, never in client-side JavaScript, to keep your secret key secure.
const crypto = require('crypto');

const secret = '•••••••••'; // Your verification secret key
const userId = current_user.id // A string UUID to identify your user

const hash = crypto.createHmac('sha256', secret).update(userId).digest('hex');

3. Identify End Users to Your AI Agent

Once you’ve generated the end user hash on your server, you can identify the end user to your AI Agent in two ways:

Identity Parameters

user_id
string
required
Unique identifier for the user from your authentication system. This tells your AI Agent which end user is currently authenticated.Format: Any string (UUID recommended)
Example: "end-user-12345", "550e8400-e29b-41d4-a716-446655440000"
To enable personalized responses and actions, create a Contact record with external_id matching this user_id using the Contacts API.
user_hash
string
required
HMAC-SHA256 hash of the user_id using your Chatbase secret key. This proves to Chatbase that the end user is authentically logged in. Must be generated on your server for security.Format: 64-character hexadecimal string
Example: "a1b2c3d4e5f6..."
user_metadata
object
Additional session-specific information about the authenticated end user. This provides context to the AI Agent about the current session.Character limit: 1000 characters total across all fields
Use for: Session state, temporary preferences, current page context, authentication level
Do not include confidential information in user_metadata such as passwords, social security numbers, credit card details, or other sensitive data. If your AI Agent needs access to confidential user information, store it securely in Contacts instead.
user_metadata: {
  "current_session": "mobile_app",
  "last_page_visited": "/dashboard",
  "auth_level": "premium_user",
  "session_preferences": { "theme": "dark" }
}

Security & Best Practices

Always generate end user hashes on your server, never in client-side JavaScript:Secure: Generate hash in your backend API
Secure: Use environment variables for Chatbase secret keys
Insecure: Generate hash in browser JavaScript
Insecure: Include secret key in client-side code
Use consistent, unique end user identifiers:Good: UUIDs (550e8400-e29b-41d4-a716-446655440000)
Avoid: Emails or usernames that might change
Keep end user metadata relevant and concise:Include: Information that helps personalize AI responses
Include: Context that aids in customer support
Avoid: Sensitive data like passwords or SSNs
Avoid: Excessive data that exceeds 1000 character limit

Troubleshooting

Symptoms: End user identity not recognized, actions using Contact data failSolutions:
  • Verify secret key matches the one from Chatbase Dashboard
  • Ensure user_id used for hashing exactly matches the one sent
  • Check that hash is generated using HMAC-SHA256
  • Confirm user_id is a string, not a number
  • Confirm user_id is the same as the one used in the Contact record
// ❌ Wrong - user_id as number
const endUserId = 12345;

// ✅ Correct - user_id as string  
const endUserId = "12345";
Symptoms: End user is verified but Contact data isn’t accessible, actions using Contact info failSolutions:
  • Verify a Contact exists with external_id matching the end user’s user_id
  • Check Contact was created using Contacts API
  • Ensure user_id and Contact external_id match exactly (case-sensitive)
  • Confirm Contact has required fields populated (e.g., Stripe accounts for payment actions)
Symptoms: End user identity lost between page loads, Contact data not maintainedSolutions:
  • Use chatbaseUserConfig for page-load identification
  • Call identify() early in your application lifecycle
  • Ensure end user hash is available before calling identify
  • Check browser console for JavaScript errors
Symptoms: Expected end user information not available to AI AgentSolutions:
  • Use Contact data for permanent end user information
  • Use user_metadata only for session-specific context
  • Reduce metadata size to under 1000 characters
  • Store comprehensive end user data in Contact custom attributes

Complete Implementation Flow

This example shows the complete flow: creating Contacts with custom attributes, then using identity verification to enable personalized AI responses.

Step 1: Create Contact on User Registration/Updates

When users sign up or their data changes, create a Contact record in Chatbase with custom attributes and Stripe customer ID:
Contact Creation API Call
const axios = require('axios');

// When user signs up or data changes
async function createChatbaseContact(userData) {
  const contactData = {
    "users": [
      {
        "external_id": userData.id,           // Your user ID
        "name": userData.name,
        "email": userData.email,
        "phonenumber": userData.phone,
        "stripe_accounts": [
          {
            "label": "Default Account",
            "stripe_id": userData.stripe_customer_id  // Stripe customer ID
          }
        ],
        "custom_attributes": {
          "signup_date": userData.signup_date,
          "support_tier": userData.support_tier
        }
      }
    ]
  };

  // Create contact via Chatbase API
  const response = await axios.post(
    `https://www.chatbase.co/api/v1/chatbot/${process.env.AGENT_ID}/contact`,
    contactData,
    {
      headers: {
        'Authorization': `Bearer ${process.env.CHATBASE_API_KEY}`,
        'Content-Type': 'application/json'
      }
    }
  );

  console.log('Contact created:', response.data);
  return response.data;
}

Step 2: Generate Hash on User Login

When users log in, generate the identity hash on your server:
Server-Side Hash Generation
const crypto = require('crypto');

function generateUserHash(userId, secret) {
  return crypto.createHmac('sha256', secret).update(userId).digest('hex');
}

// Login endpoint
app.post('/api/login', async (req, res) => {
  const { email, password } = req.body;
  
  // Authenticate user with your existing logic
  const user = await authenticateUser(email, password);
  if (!user) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }
  
  // Generate secure hash for identity verification
  const userHash = generateUserHash(user.id, process.env.CHATBASE_SECRET);
  
  res.json({
    user: user,
    userHash: userHash  // Send to frontend for identify call
  });
});

Step 3: Identify User in Frontend

Use the hash to identify the user to Chatbase widget:
Frontend Identity Verification
// After successful login
async function loginUser() {
  const response = await fetch('/api/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email: 'user@example.com', password: 'password' })
  });
  
  const { user, userHash } = await response.json();
  
  // Identify user to Chatbase - enables access to Contact data
  window.chatbase("identify", {
    user_id: user.id,
    user_hash: userHash,
    user_metadata: {
      "name": user.name,
      "email": user.email,
      "current_page": "dashboard"
    }
  });
  
  console.log('User identified - AI Agent can now access Contact data and perform Stripe actions');
}

Step 4: Unlock Powerful Custom Actions with Contact Data 🚀

Now that your AI Agent has access to rich contact data, it can perform incredibly sophisticated custom actions that were previously impossible!

Step 5: Unlock Stripe Actions 💳

Here’s where the magic really happens! By adding stripe_accounts to your contacts, you’ve just unlocked the full power of our Stripe integration. Your AI Agent can now handle complex billing operations seamlessly without any additional coding on your part.
Game Changer Alert: Your customers can now say things like “Cancel my subscription”, “Show me my last invoice”, or “Update my payment method” and your AI Agent will handle these requests intelligently with full context about their account!
What This Means for Your Business:
  • Reduced Support Tickets: Common billing questions are handled instantly
  • Improved Customer Experience: No more “let me transfer you to billing”
  • Increased Efficiency: One AI Agent handles both support AND billing operations
  • Personalized Service: Every interaction is tailored to the customer’s specific account details

Next Steps

I