Developer

Widget SDK

Embed and control the ConverseLead chat widget on your website using the JavaScript SDK.

Installation

Add the widget script before the closing </body> tag on every page where you want the chat widget to appear.

<script src="https://your-server.com/static/widget.js"></script>
<script>
  clchat('init', { apiKey: 'cl_YOUR_API_KEY' });
</script>

The script automatically detects its own URL and uses the same origin for API calls, so no additional server configuration is needed.

API Overview

All widget methods are called through the global clchat() function. The first argument is always the method name, followed by an optional options object.

clchat('methodName', { /* options */ });

Available methods:

init

Initialize the widget. This must be called once on page load before using any other method.

clchat('init', {
  apiKey: 'cl_YOUR_API_KEY',
  primaryColor: '#8b5cf6',
  position: 'right',
});

Options

identify

Link the current chat visitor to a known user in your application. This enables you to see customer names, emails, and metadata in the admin dashboard, and automatically promotes the contact from “lead” to “customer” status.

clchat('identify', {
  externalUserId: 'user_12345',
  name: 'Jane Doe',
  email: '[email protected]',
  phone: '+1 555-0100',
  company: 'Acme Inc',
  metadata: {
    plan: 'enterprise',
    accountId: 'acc_789',
  },
});

Options

When to call identify

Call identify whenever you know who the user is:

• After login — right after your user authenticates
• On page load — if the user is already logged in (check your session)
• After sign-up — immediately after account creation

You can call identify at any time — before or after a conversation has started. If a conversation already exists, the contact information is updated in place.

Example: React integration

import { useEffect } from 'react';
import { useUser } from './auth'; // your auth hook

function App() {
  const user = useUser();

  useEffect(() => {
    // Initialize widget once
    clchat('init', { apiKey: 'cl_YOUR_API_KEY' });
  }, []);

  useEffect(() => {
    // Identify when user logs in
    if (user) {
      clchat('identify', {
        externalUserId: user.id,
        name: user.name,
        email: user.email,
        metadata: {
          plan: user.plan,
          role: user.role,
        },
      });
    }
  }, [user]);

  return <div>...</div>;
}

Example: Next.js integration

// app/layout.tsx or a client component
'use client';

import { useEffect } from 'react';
import Script from 'next/script';

export function ChatWidget({ user }) {
  useEffect(() => {
    if (typeof window.clchat === 'undefined') return;

    clchat('init', { apiKey: 'cl_YOUR_API_KEY' });

    if (user) {
      clchat('identify', {
        externalUserId: user.id,
        name: user.name,
        email: user.email,
      });
    }
  }, [user]);

  return (
    <Script
      src="https://your-server.com/static/widget.js"
      strategy="afterInteractive"
    />
  );
}

open & close

Programmatically control the widget visibility. Useful for triggering the chat from custom UI elements.

// Open the chat window
clchat('open');

// Close the chat window
clchat('close');

Common use cases

• Custom “Need help?” button that opens the chat
• Triggering chat after a failed action (e.g. payment error)
• Opening chat from a help menu or navigation link
• Closing chat after a successful resolution

<!-- Custom help button -->
<button onclick="clchat('open')">
  Need help? Chat with us
</button>

logout

Clear the current visitor session and reset the widget to an anonymous state. Call this when your user logs out of your application.

// When user logs out of your app
function handleLogout() {
  // Clear your app's session
  auth.signOut();

  // Reset the chat widget
  clchat('logout');
}

This clears all locally stored data (visitor ID, conversation history reference, contact info). The next visitor will get a fresh, anonymous session.

Visitor Lifecycle

Every visitor gets an automatically generated anonymous ID that persists across page loads on the same domain.

• Generated automatically on the first init call if none exists
• Survives page navigations and full page refreshes
• Cleared when logout is called or browser storage is cleared
• Unique per domain — different sites and incognito windows get separate IDs

The visitor ID is the foundation of session continuity. It allows a visitor to return to your site and see their previous conversation history, even if they haven't identified themselves.

Conversation Behavior

Lazy creation

Conversations are created only when the visitor sends their first message, not when the widget loads. This means:

• No empty conversations clutter your dashboard from page views
• Bot traffic and idle visitors don't create noise
• Conversation counts accurately reflect real engagement

Conversation expiry

After 30 minutes of inactivity (configurable), the widget automatically starts a new conversation the next time the visitor sends a message. The previous conversation is preserved and remains accessible in the admin dashboard.

Conversation history

When a returning visitor opens the widget, their most recent conversation is loaded automatically with full message history. Older messages are loaded on scroll via pagination.

File Sharing

Visitors can share files directly through the chat widget using the attachment button. Supported file types:

Maximum file size is 50 MB. Images and videos are displayed inline in the conversation. Documents and other files appear as downloadable attachments.

Escalation to Human

The widget includes a built-in “Talk to a human” option that visitors can use to request a human agent. When triggered:

• The AI stops responding automatically
• A banner appears: “A human will respond shortly”
• Your team is notified via email and/or Slack (if configured)
• Once an agent replies, the banner disappears and the conversation continues normally

The AI can also trigger escalation automatically when it determines the visitor needs human assistance.

Real-time Features

The widget maintains a live connection for real-time updates:

• Instant messages — agent replies appear immediately without polling
• Typing indicators — visitors see animated dots when an agent is typing
• Status updates — escalation banners and conversation state changes are reflected live
• Background notifications — badge, toast, and sound alerts when the widget is minimized

The connection automatically reconnects if it drops due to network issues.

Notifications

When the widget is minimized, visitors are notified of new messages through multiple channels:

• Unread badge — a red counter appears on the chat bubble
• Toast preview — a small popup shows the agent name and message snippet
• Sound — a short chime plays (disable with notificationSound: false)
• Desktop notifications — browser notifications when enabled and permitted

Opening the widget clears the badge and marks all messages as read. The unread state persists across page reloads.

Options

Configure notification behavior through init options:

clchat('init', {
  apiKey: 'cl_YOUR_API_KEY',

  // Notification options
  notificationSound: true,      // Play a chime on new messages (default: true)
  desktopNotifications: false,   // Browser notifications (default: false)
  autoOpenOnReply: false,        // Auto-open widget on reply (default: false)
  onNewMessage: function(data) { // Callback for new messages (optional)
    console.log(data.agentName + ': ' + data.content);
  },
});

onNewMessage callback

Use the onNewMessage callback to react to incoming messages in your own UI — for example, showing a custom banner or tracking analytics.

clchat('init', {
  apiKey: 'cl_YOUR_API_KEY',
  onNewMessage: function(data) {
    console.log(data.agentName + ': ' + data.content);
  },
});

The callback receives a single object with the following fields:

CSS Isolation

The widget renders inside an iframe, so its styles are fully isolated from your page. Your CSS won't affect the widget, and the widget won't affect your page layout.

Troubleshooting

Widget doesn't appear

• Verify the script URL is correct and accessible
• Check the browser console for errors
• Ensure clchat('init', ...) is called after the script has loaded
• Confirm your API key is valid and matches the website in your dashboard

Chat history not loading

• The visitor ID is stored in localStorage. If your site clears storage, history will be lost.
• Different subdomains are treated as different sites. Use the same domain for continuity.
• Incognito/private browsing starts a fresh session every time.

identify not working

• Make sure init has been called first
• The contact may take a moment to appear in the admin dashboard
• Check that at least one field (email, name, or externalUserId) is provided