Add CometChat Widget to Shopify

Add the CometChat Widget with a single snippet inside your Shopify theme. Choose the sign-in flow that matches your store: guests, auto-created users from Shopify customers, or backend-issued auth tokens. Choose how shoppers sign in:

Anonymous Chat (Guest Mode)

Visitors can chat without accounts.
Fastest, friction-free setup.

Create + Log In User On The Fly (Shopify Customers)

Auto-create CometChat users from Shopify customers.
Falls back to guests when no one is logged in.

Backend-Created User (Auth Token Login)

Use your backend to issue auth tokens.
Keep your Auth Key off the storefront.

Where to paste the snippet in Shopify

In Shopify Admin, go to Online Store → Themes → … → Edit code.
Open layout/theme.liquid (or a section where you want the widget).
Scroll near </body> and paste the snippet from the option you choose.
Save and refresh your storefront to confirm chat loads.
For page-specific placement, paste the snippet into a section or template instead of the global layout.

1. Anonymous Chat (Guest Mode)

Use this when: you want anyone to chat without signing in.

Paste this near `</body>` in `layout/theme.liquid`

<div id="cometChatMount"></div>
<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>

<script type="module">
  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",
    mode: "guest",
    authKey: "YOUR_AUTH_KEY",

    user: {
      name: "Guest User",
      avatar: "",
      link: ""
    },

    mount: "#cometChatMount",
    width: "450px",
    height: "80vh",
    isDocked: true,
    //variantID: "YOUR_VARIANT_ID",
    //chatType: "user" | "group",
    //defaultChatID: "uid_or_guid",
    //dockedAlignment: "left" | "right"
  };

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

Update these values:

appID, region, authKey: Copy from the CometChat Dashboard (use an App Auth Key, not REST API key).
user.name, user.avatar, user.link: Optional guest display info.
width, height, isDocked: Size/placement (isDocked = true shows a docked bubble).
variantID, chatType, defaultChatID, dockedAlignment: Optional widget targeting/placement controls.

2. Create + Log In User On The Fly (Shopify Customers)

Use this when: you have Shopify customer accounts and want logged-in shoppers to automatically become CometChat users. Falls back to a persistent guest ID for visitors.

Turn on Shopify customer accounts so {{ customer.id }} and {{ customer.first_name }} populate.

Paste this near `</body>` in `layout/theme.liquid`

<div id="cometChatMount"></div>
<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>

<script type="module">
  const SHOPIFY_CUSTOMER_ID = {{ customer.id | json }};
  const SHOPIFY_CUSTOMER_NAME = {{ customer.first_name | json }};

  const uidFromShopify = SHOPIFY_CUSTOMER_ID ? String(SHOPIFY_CUSTOMER_ID) : null;
  const savedGuestId = localStorage.getItem("cometchat_guest_uid") || `guest_${Date.now()}`;
  localStorage.setItem("cometchat_guest_uid", savedGuestId);

  const uid = uidFromShopify || savedGuestId;
  const name = SHOPIFY_CUSTOMER_NAME || "Guest User";

  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",
    mode: "uid",
    authKey: "YOUR_AUTH_KEY",

    uid,
    user: {
      name,
      avatar: "",
      link: ""
    },

    mount: "#cometChatMount",
    width: "450px",
    height: "80vh",
    isDocked: true,
    //variantID: "YOUR_VARIANT_ID",
    //chatType: "user" | "group",
    //defaultChatID: "uid_or_guid",
    //dockedAlignment: "left" | "right"
  };

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

Update these values:

appID, region, authKey: Copy from Dashboard (App Auth Key).
uid: Leave as-is; it pulls Shopify customer ID or a stored guest ID.
user.name, user.avatar, user.link: Optional profile info shown in chat.
width, height, isDocked, variantID, chatType, defaultChatID, dockedAlignment: Optional UI/placement controls.

How it works:

Uses Shopify customer.id + customer.first_name when a shopper is logged in.
Stores a stable guest ID in localStorage for visitors so their chat history persists across pages.
CometChat auto-creates the UID the first time it sees it.

Use this when: people sign in through your backend and you generate their CometChat auth token server-side. This keeps your Auth Key off the page. Server-side flow (auth token login):

Authenticate the user in your app.
If it’s their first time, call Create User (https://www.cometchat.com/docs/rest-api/users/create) — you can also request an auth token in that call.
For returning users, call Create Auth Token (https://www.cometchat.com/docs/rest-api/auth-tokens/create) to issue a fresh token.
Send the token to the browser and place it in the widget config below.
The same token works for the CometChat Widget, UI Kit, or SDK.

Full walkthrough: How to properly log in and create users in CometChat. Use this when: you issue CometChat auth tokens from your backend and don’t want an Auth Key in the browser.

Paste this near `</body>` in `layout/theme.liquid`

<div id="cometChatMount"></div>
<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.x.x/dist/main.js"></script>

<script type="module">
  const COMETCHAT_WIDGET_CONFIG = {
    appID: "YOUR_APP_ID",
    region: "YOUR_APP_REGION",
    mode: "authToken",

    // Inject the token your backend generated for the logged-in customer
    authToken: "USER_AUTH_TOKEN",

    mount: "#cometChatMount",
    width: "450px",
    height: "80vh",
    isDocked: true,
    //variantID: "YOUR_VARIANT_ID",
    //chatType: "user" | "group",
    //defaultChatID: "uid_or_guid",
    //dockedAlignment: "left" | "right"
  };

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

Update these values:

appID, region: Copy from Dashboard.
authToken: Generate server-side after the user logs in (using CometChat Auth Token API) and output it into this snippet (e.g., from a Shopify app proxy or metafield).
UI options: width, height, isDocked, variantID, chatType, defaultChatID, dockedAlignment.

Optional: Make credentials editable in Theme settings

Add this block to config/settings_schema.json (just before the final ]). Then replace hardcoded values in the snippets with {{ settings.cometchat_app_id }} etc.

,
{
  "name": "CometChat Settings",
  "settings": [
    {
      "type": "text",
      "id": "cometchat_app_id",
      "label": "CometChat App ID",
      "default": "YOUR_APP_ID"
    },
    {
      "type": "text",
      "id": "cometchat_app_region",
      "label": "CometChat App Region",
      "default": "YOUR_REGION"
    },
    {
      "type": "text",
      "id": "cometchat_auth_key",
      "label": "CometChat Auth Key",
      "default": "YOUR_AUTH_KEY"
    }
  ]
}

Optional: Add as an Online Store 2.0 section/app block

Online Store → Themes → Edit code.
Under Sections, create cometchat-widget.liquid and paste one of the snippets above.
Save, then add it in Customize theme under App embeds or as a section on any template:

{% section 'cometchat-widget' %}

Advanced JavaScript Controls

The embed works out of the box. Use the helpers below only if you need to open a specific chat, listen for widget events, or change settings on the fly.

Before you follow advanced setup steps

Keep the standard widget snippet (from the Integration guide) on your page.
Add another <script type="module"> right after it or inside your site builder’s “custom code” area.
Wrap your code in window.addEventListener("DOMContentLoaded", () => { ... }) so it runs after the widget loads.
Replace placeholder text such as UID, GUID, and LANGUAGE_CODE with your real values.

When the widget is ready, it exposes a global helper named CometChatApp. Every example below shows a tiny recipe you can paste inside the script mentioned above.

Open a chat or start a call

Use these helpers when you want the widget to jump straight to a person/group or begin a call. Drop the snippet inside your custom script and replace UID/GUID with real IDs from your CometChat app.

// Open chat with a specific person
CometChatApp.chatWithUser("UID");

// Open chat with a specific group
CometChatApp.chatWithGroup("GUID");

// Start a call with a person or a group
CometChatApp.callUser("UID");
CometChatApp.callGroup("GUID");

// Toggle extra UI bits
CometChatApp.showGroupActionMessages(true); // Show join/leave messages
CometChatApp.showDockedUnreadCount(true);   // Show unread badge on docked bubble

Run your own code when something happens inside the widget—new message, docked bubble opened, or someone switching chats. Keep the event names as shown; just change what happens inside each arrow function.

// Fire when a new message arrives
CometChatApp.uiEvent("onMessageReceived", (message) => {
  console.log("New message:", message);
});

// Fire when the docked bubble opens or closes
CometChatApp.uiEvent("onOpenChat", () => console.log("Chat opened"));
CometChatApp.uiEvent("onCloseChat", () => console.log("Chat closed"));

// Fire when the user switches between conversations
CometChatApp.uiEvent("onActiveChatChanged", (chat) => {
  console.log("Now viewing:", chat);
});

Create/Update users on the fly

This will only work with authKey

If you collect names, avatars, or profile links on your site, you can push them straight into CometChat. Replace the placeholders and run the snippet after the widget loads.

// Create or update a user
const user = new CometChatApp.CometChat.User("UID");
user.setName("User Name");
user.setAvatar("https://example.com/avatar.png");
user.setLink("https://example.com/profile");

CometChatApp.createOrUpdateUser(user).then((result) => {
  console.log("User saved:", result);
});

Create/Update groups on the fly

If you want to create groups directly from your page, use this snippet. Replace the placeholders and run the snippet after the widget loads.

// Create or update a group
const group = new CometChatApp.CometChat.Group("GUID", "GROUP_NAME", "public");

CometChatApp.createOrUpdateGroup(group).then((result) => {
  console.log("Group saved:", result);
});

Log users in or out with code

Use an auth token if you have a backend, or fall back to a plain UID for quick tests. Run these helpers after the widget loads.

// Sign in with a secure auth token from your server
CometChatApp.login({ authToken: "USER_AUTH_TOKEN" });

// ...or sign in directly with a UID (less secure, but fast for demos)
CometChatApp.login({ uid: "UID" });

// Sign the current user out
CometChatApp.logout();

// Listen for logout so you can clean up your UI
CometChatApp.uiEvent("onLogout", () => {
  console.log("User logged out");
});

Control where data is stored

Pick whether the widget should remember login info in the browser tab only (SESSION) or across visits (LOCAL). Update the placeholders, then drop this script right after the default widget embed.

const COMETCHAT_DATA = {
  appID: "<YOUR_APP_ID>",
  appRegion: "<YOUR_APP_REGION>",
  authKey: "<YOUR_AUTH_KEY>",
  storageMode: "SESSION", // or "LOCAL" (default)
};

const COMETCHAT_USER_UID = "UID"; // The person who should log in

const COMETCHAT_LAUNCH_OPTIONS = {
  targetElementID: "cometChatMount",
  isDocked: true,
  width: "700px",
  height: "500px",
};

window.addEventListener("DOMContentLoaded", () => {
  CometChatApp.init(COMETCHAT_DATA)
    .then(() => CometChatApp.login({ uid: COMETCHAT_USER_UID }))
    .then(() => CometChatApp.launch(COMETCHAT_LAUNCH_OPTIONS))
    .catch(console.error);
});

// Optional extras:
// COMETCHAT_LAUNCH_OPTIONS.variantID = "YOUR_VARIANT_ID";
// COMETCHAT_LAUNCH_OPTIONS.chatType = "user" | "group";
// COMETCHAT_LAUNCH_OPTIONS.defaultChatID = "uid_or_guid";
// COMETCHAT_LAUNCH_OPTIONS.dockedAlignment = "left" | "right";

The widget auto-detects the browser language, but you can force it to any supported locale. Run the helper once after the widget loads and swap in the language code you need.

CometChatApp.localize("en-US"); // Example: force English (United States)

Popular codes

Language	Code
English (United States)	`en-US`
English (United Kingdom)	`en-GB`
Dutch	`nl`
French	`fr`
German	`de`
Hindi	`hi`
Italian	`it`
Japanese	`ja`
Korean	`ko`
Portuguese	`pt`
Russian	`ru`
Spanish	`es`
Turkish	`tr`
Chinese (Simplified)	`zh`
Chinese (Traditional)	`zh-TW`
Malay	`ms`
Swedish	`sv`
Lithuanian	`lt`
Hungarian	`hu`

Need another locale? Use the same pattern with its code (for example CometChatApp.localize("ko") for Korean).

Troubleshooting

Widget not appearing? Confirm the embed script loads (chat-embed@1.x.x), the mount div exists, and no ad blockers or CSP rules are blocking it.
Shopify customer info not showing? Ensure customer accounts are enabled and you’re previewing as a logged-in shopper (not just the Theme Editor).
Login/auth errors? For UID mode, verify the Auth Key is an App Auth Key and UIDs are unique; for auth token mode, ensure the token matches the logged-in user.
Docked vs embedded view wrong? Adjust isDocked, width, height, and optional alignment settings.
Still stuck? Inspect CometChatApp.CometChatAuth calls in the browser console for errors.

Need Help?

Reach out to CometChat Support or visit our docs.

Add CometChat Widget to Shopify

Anonymous Chat (Guest Mode)

Create + Log In User On The Fly (Shopify Customers)

Backend-Created User (Auth Token Login)

Where to paste the snippet in Shopify

1. Anonymous Chat (Guest Mode)

Paste this near `</body>` in `layout/theme.liquid`

2. Create + Log In User On The Fly (Shopify Customers)

Paste this near `</body>` in `layout/theme.liquid`

Paste this near `</body>` in `layout/theme.liquid`

Optional: Make credentials editable in Theme settings

Optional: Add as an Online Store 2.0 section/app block

Advanced JavaScript Controls

Before you follow advanced setup steps

Open a chat or start a call

Listen for widget events

Create/Update users on the fly

Create/Update groups on the fly

Log users in or out with code

Control where data is stored

Change the widget language

Troubleshooting

Need Help?

Anonymous Chat (Guest Mode)

Create + Log In User On The Fly (Shopify Customers)

Backend-Created User (Auth Token Login)

​Where to paste the snippet in Shopify

​1. Anonymous Chat (Guest Mode)

​Paste this near </body> in layout/theme.liquid

​2. Create + Log In User On The Fly (Shopify Customers)

​Paste this near </body> in layout/theme.liquid

​3. Backend-Created User (Auth Token Login)

​Paste this near </body> in layout/theme.liquid

​Optional: Make credentials editable in Theme settings

​Optional: Add as an Online Store 2.0 section/app block

​Advanced JavaScript Controls

​Before you follow advanced setup steps

​Open a chat or start a call

​Listen for widget events

​Create/Update users on the fly

​Create/Update groups on the fly

​Log users in or out with code

​Control where data is stored

​Change the widget language

​Troubleshooting

​Need Help?

Where to paste the snippet in Shopify

1. Anonymous Chat (Guest Mode)

Paste this near `</body>` in `layout/theme.liquid`

2. Create + Log In User On The Fly (Shopify Customers)

Paste this near `</body>` in `layout/theme.liquid`

3. Backend-Created User (Auth Token Login)

Paste this near `</body>` in `layout/theme.liquid`

Optional: Make credentials editable in Theme settings

Optional: Add as an Online Store 2.0 section/app block

Advanced JavaScript Controls

Before you follow advanced setup steps

Open a chat or start a call

Listen for widget events

Create/Update users on the fly

Create/Update groups on the fly

Log users in or out with code

Control where data is stored

Change the widget language

Troubleshooting

Need Help?