Add CometChat Widget to WordPress via Plugin

Comprehensive guide to install, configure, and extend the new CometChat WordPress plugin.

Using the v1 widget (Chat Embed @1.x.x)? Widgets created in the CometChat Dashboard now use v2. Please upgrade to v2. v2 is published on npm under the next tag today; in a future update it will become the default (latest) version and v1 will be marked as legacy. On WordPress the plugin picks the widget version: update to plugin 0.0.15 or later and add version="v2" to your shortcode. A shortcode without version keeps loading v1. Check your custom CSS, JavaScript and variant settings against Upgrade from v1 to v2 before you switch.

​

Before getting started

Go through the Overview to generate your Widget from the CometChat Dashboard.
Ensure you have:

• A WordPress site (5.0+)
• PHP 7.2 or higher
• Your App ID, Region, and REST API Key

​

Quick Steps to Embed CometChat Widget

1. Download the Plugin ZIP

   1. Download the CometChat plugin from here.
   2. Save the cometchat-pro.zip file to your computer.
2. Install & Activate the Plugin

   1. In WordPress Admin, navigate to Plugins → Add Plugin.

   

   2. Click Upload Plugin, choose cometchat-pro.zip, and click Install Now.

   

   3. Once installed, click Activate Plugin.

   
3. CometChat Credentials

   To use CometChat UI Kit, you first need to register on the CometChat Dashboard.

   After registering, create a new app and retrieve your authentication details:

   1. Navigate to Application, then select the Credentials section.

   2. Note down the following:

      • App ID
      • Region
      • REST API Key (from Credentials → REST API Keys)
4. Configure Plugin Settings

   1. In WordPress Admin, go to Settings → CometChat (or click Settings on the CometChat row under Plugins).
   2. Fill in:
      • App ID and App Region — from Dashboard → App → Credentials.
      • API Version — select 3. Leaving this unset falls back to the legacy v2 API and user creation will fail.
      • REST API Key — from Dashboard → App → Credentials → REST API Keys. This is the REST API key, not the Auth Key.
   3. Click Update Settings.

   How users are authenticated: The plugin renders the chat widget on your site’s frontend only for logged-in WordPress users — it is gated by WordPress’s is_user_logged_in(). For each logged-in visitor, the plugin automatically maps the WordPress user to a CometChat user whose UID is the WordPress numeric user ID and signs them in with a securely generated auth token; you do not configure a fixed user UID in the plugin. Logged-out visitors don’t see the widget — the shortcode renders the literal text “Please login to use this feature.” instead. Where the widget appears (inline vs. floating) is set per placement by the shortcode’s docked attribute, shown below.

5. Embed Widget Inline (Embedded Mode)

   1. Edit any Page/Post, add a Shortcode block, and insert:
      [cometchat 
        version="v2"                       <!-- Chat Embed version: v2 (current) or v1. Omitted = v1 -->
        width="600px"                      <!-- Widget width (Required) -->
        height="600px"                     <!-- Widget height (Required) -->
        docked="false"                     <!-- true = floating bubble, false = embedded (Required) -->
        variant-id="default-variant"       <!-- Optional | Variant ID -->
        chat-type="user"                   <!-- Optional | user / group -->
        default-chat-id="uid_or_guid"      <!-- Optional | UID or GUID to open by default -->
      ]
      
   2. Publish or update the Page/Post.

   Widget version: version selects the Chat Embed release the plugin loads. Widgets built in the dashboard today are v2, so include version="v2". Leave it out and the plugin loads v1, which keeps shortcodes written before v2 working unchanged. The attribute needs plugin 0.0.15 or later; earlier plugin versions ignore it and load v1.

6. Docked Widget (Floating Mode)

   1. Edit any Page/Post (or site-wide), add a Shortcode block, and insert:
      [cometchat 
        version="v2"                       <!-- Chat Embed version: v2 (current) or v1. Omitted = v1 -->
        width="400px"                      
        height="800px"                     
        docked="true"                      <!-- true = floating bubble, false = embedded (Required) -->
        variant-id="default-variant"       <!-- Optional | Variant ID -->
        docked-alignment="right"           <!-- Optional | left / right (only applies if docked=true) -->
        chat-type="user"                   <!-- Optional | user / group -->
        default-chat-id="uid_or_guid"      <!-- Optional | UID or GUID to open by default -->
      ]
      
   2. Publish or update to see the widget docked on the chosen side.
7. Show the Docked Widget on Every Page

   In Settings → CometChat, paste your docked shortcode (docked="true") into the “Load CometChat on all pages/sitewide?” field and click Update Settings. The plugin then renders the widget in the footer of every page for logged-in WordPress users.

   For logged-out visitors, a sitewide shortcode prints “Please login to use this feature.” on every page. Leave the field blank or hide #cometchat via CSS if that isn’t wanted.

---

​

Advanced JavaScript APIs

Once the widget is loaded, interact with it via the global CometChatApp object:

​

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

​

Listen for widget events

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);
});

​

Change the widget language

The widget starts in the locale you set with the language launch option, and falls back to en-US when you do not set one. You can switch locale at any time after load — run the helper 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).

---

​

Anonymous & guest access

Because the widget is gated by WordPress login, visitors who are not signed in to WordPress won’t see it — the shortcode only renders for logged-in WordPress users.

• Member sites: no extra setup — your existing WordPress login is the gate, and the plugin authenticates each signed-in member automatically.
• Guest / anonymous chat: not supported by the WordPress plugin. If you need anonymous chat, use the HTML/JS embed with mode: "guest" on those pages instead of the plugin shortcode.

---

​

Customize the widget with CSS

The Widget Builder includes a Custom Code tab where you can add Custom CSS (and Custom JS) that ships with your widget.

Open it from the dashboard: Chat & Messaging → Get Started / Integrate → No Code → WordPress → Widget Builder → Custom Code tab.

Set your brand color, text colors, font and font size in the Builder’s Styles tab, not here. Those are first-class controls, and the Builder applies them as inline styles that a stylesheet rule cannot cleanly override. Custom CSS is for the things the Builder does not expose.

Custom CSS is automatically scoped under the widget’s root, so top-level selectors like :root or body never match — write ordinary component selectors instead. The scoping also adds specificity for you, so these rules win without !important.

Example — square off the message bubbles and the search bar:

.cometchat-message-bubble__body {
  border-radius: 4px;
}

.cometchat-search-bar {
  border-radius: 8px;
}

Save and re-publish in the Widget Builder, then re-copy the embed code if your Variant ID changed.

​

What to know before you write Custom CSS

Component classes are the stable target. Every component carries a cometchat-* block class with BEM elements under it — .cometchat-message-bubble__body, .cometchat-conversations__item, .cometchat-message-composer__send-button. Inspect the widget to find the one you want. Prefer a plain property (spacing, radius, borders, display) over redefining a --cometchat-* variable: variables are resolved higher up the tree and some are composed into other variables before your rule is reached, so a variable override can appear to apply while changing nothing.

At-rules do not work here. @font-face, @media and @import are dropped: every top-level selector is scoped automatically, and that scoping makes an at-rule invalid, so the browser discards it silently. Stick to declarations inside ordinary selectors.

Dialogs and call screens sit outside .cometchat-root. Confirmation dialogs, the call screen and context menus are rendered at the widget’s outer element so they can cover the chat. Their own component classes still work — just do not nest your selector under .cometchat-root.

---

​

Troubleshooting

• Plugin upload fails: Ensure the ZIP is intact and WordPress has write permissions.
• Settings not saving: Temporarily disable caching/minification plugins.
• Shortcode not working: Verify the [cometchat] syntax and saved settings.
• Widget still loads v1 after adding version="v2": Update the plugin to 0.0.15 or later from Plugins → Updates, or re-upload the ZIP from the link above. Earlier plugin versions ignore the attribute.
• JavaScript errors: Check browser console for missing CometChatApp or invalid parameters.

---

​

Need Help?

Questions or issues? Contact CometChat Support.