Skip to main content
Using the v1 widget (Chat Embed @1.x.x)? Widgets created in the CometChat Dashboard now use v2 (@cometchat/chat-embed@2.x.x). On npm, v2 is published under the next tag — latest and a bare package name still resolve to v1 — and existing embeds that load @1.x.x keep running v1 until you change the script tag. Please upgrade to v2. In a future update, v2 will become the default (latest) version on npm and v1 will be marked as legacy. Before you upgrade, read Upgrade from v1 to v2: v2 renames CSS classes, so custom CSS and JavaScript may need updating.

Prerequisites

  • CometChat app (App ID, Region, Auth Key).
  • An AI Agent widget variant. A standard Chat Widget variant will render a chat with your agent, but the agent-only options below (aiAssistantTools, parentMessageId, loadLastAgentConversation) have no effect on it. Create one from:
    • CometChat AI Agents — AI Agents → Create an Agent, or for an agent you already have, Manage Agent → Deploy → Launch Widget Builder.
    • Bring Your Own Agent — BYO Agents → Create an Agent, or for an existing agent, Add to Frontend.
  • An AI Agent already created and enabled in your app via:
  • Agent ID and (optional) variant set to default to that agent.
  • (Optional) Frontend Action definitions if you want UI‑bound behaviors.

Step 1 - Publish & Embed

Open the widget builder for your agent — Manage Agent → Deploy → Launch Widget Builder for a CometChat agent, or Add to Frontend for a BYO agent — then click Get Embed Code. This publishes your agent widget variant and shows an App Credentials panel — copy all four values:
  • App ID
  • Region
  • Auth Key
  • Variant ID
You will also need your Agent ID, from AI Agents in the Dashboard.
For an agent widget, all three of variantID, chatType: "user" and defaultChatID are required. The variant ID on its own mounts an empty widget, because the agent surface needs the agent resolved from defaultChatID before it renders.(Outside the agent setup, variantID is optional — a standard chat widget falls back to the first available variant for the app.)
Example embed (HTML):
1

Include script (<head>)

Add script tag in document head (see snippet below).
2

Initialize (<body> end)

Add mount div + init script before closing body.
Choose the auth flow that matches your site:

Option A - Anonymous (Guest Mode)

Use this when:
  • Let anyone chat anonymously without signing up or logging in.
  • Perfect for marketing pages, help centers, or demo sites.

Option B - Create + Log In User On The Fly (Auth Key + UID)

Use this when:
  • Use your existing user IDs (email, username etc.) to create and log in users automatically.
  • No backend needed—CometChat creates users the first time they visit.

Option C - Backend-Created User (Auth Token Login)

Use this when:
  • Create your users via server and login them using secure auth token on frontend.
  • Ideal for sites with existing login systems and backends.
Replace the placeholder values (app ID, region, auth key or auth token, UID, agent ID, and variant ID) with values from your deployment. Keep chatType: "user" and set defaultChatID to your agent for an AI-first experience.

Options that apply only to an agent widget

aiAssistantTools, parentMessageId and loadLastAgentConversation take effect only on a widget built from an AI agent variant. On a standard chat variant they are accepted and ignored — including when that variant is opened on an agent through defaultChatID.

Resuming the previous conversation

By default the widget opens a fresh conversation with the agent every time it loads. Add loadLastAgentConversation to continue where the user left off instead:
This only has an effect for a user the widget can recognise on their next visit — uid or authToken mode. In guest mode the widget stores the generated UID in a cookie, so clearing cookies or switching browser starts a new conversation.

Step 2 - Verify

If responses fail, confirm the endpoint is publicly reachable and the Agent ID matches the Dashboard configuration.

Troubleshooting