Skip to main content

​
Prerequisites

  • CometChat app (App ID, Region, Auth Key).
  • Chat Widget variant configured in UI Kit Builder.
  • 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.
Finish agent creation first in Agent Builder or Bring Your Own Agent, then continue here to embed the widget.

​
Step 1 - Export & Embed

In UI Kit Builder click Get Embedded Code → copy credentials:
  • App ID
  • Auth Key
  • Region
  • Variant ID
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.
<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>
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.
<div id="cometChatMount"></div>

<script type="module">

  //  EDIT ONLY THE TEXT INSIDE QUOTES
  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",   // e.g. "us", "eu", "in"
    mode: "guest",
    authKey: "YOUR_AUTH_KEY",

    // Optional: how the guest appears in chat
    user: {
      name: "Guest User",
      avatar: "",
      link: ""
    },

    // Widget placement + size
    mount: "#cometChatMount",
    width: "700px",
    height: "500px",
    isDocked: true,
    chatType: "user",
    defaultChatID: "<YOUR_AGENT_ID>",  // point to your AI agent
    variantID: "<YOUR_VARIANT_ID>",
    //dockedAlignment: "left" | "right"
  };

  CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);
</script>

​
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.
<div id="cometChatMount"></div>

<script type="module">

  //  EDIT ONLY THE TEXT INSIDE QUOTES
  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",      // e.g. "us", "eu", "in"
    mode: "uid",
    authKey: "YOUR_AUTH_KEY",

    // IMPORTANT: this must be unique per user
    uid: "UNIQUE_USER_ID",          // e.g. "user_123", "customer_42"

    // Optional: user profile shown in chat
    user: {
      name: "User Name",
      avatar: "https://example.com/uid.png",
      link: "https://example.com/profile/uid"
    },

    // Widget placement + size
    mount: "#cometChatMount",
    width: "700px",
    height: "500px",
    isDocked: true,
    chatType: "user",
    defaultChatID: "<YOUR_AGENT_ID>",  // open AI agent by default
    variantID: "<YOUR_VARIANT_ID>",
    //dockedAlignment: "left" | "right"
  };

  CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);
</script>

​
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.
<div id="cometChatMount"></div>

<script type="module">

  //  EDIT ONLY THE TEXT INSIDE QUOTES
  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",       // e.g. "us", "eu", "in"
    mode: "authToken",

    // Generated BY YOUR BACKEND after user login
    authToken: "USER_AUTH_TOKEN",

    // Widget placement + size
    mount: "#cometChatMount",
    width: "700px",
    height: "500px",
    isDocked: true,
    chatType: "user",
    defaultChatID: "<YOUR_AGENT_ID>",   // open AI agent by default
    variantID: "<YOUR_VARIANT_ID>",
    //dockedAlignment: "left" | "right"
  };

  CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);
</script>
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.

​
Step 2 - Verify

CheckHow
Agent appearsOpen widget → new conversation / agent entry available
Basic replySend a prompt → response under a few seconds
Tool logic worksAsk for a tool-backed request (e.g., recipe lookup or data fetch)
Error freeBrowser console + agent logs have no unhandled errors
If responses fail, confirm the endpoint is publicly reachable and the Agent ID matches the Dashboard configuration.

​
Troubleshooting

IssueFix
Agent not listedConfirm it’s enabled in Dashboard + variant saved
404 from agentEndpoint path or agent key mismatch
TimeoutExpose via a tunnel or deploy to a public host
Tool not invokedEnsure tool ID referenced in agent instructions & code
Auth errorRe-check Auth Key / App credentials in embed snippet