Add CometChat Widget to WordPress via Plugin

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

Download the Plugin ZIP

Download the CometChat plugin from here.
Save the cometchat-pro.zip file to your computer.

Install & Activate the Plugin

In WordPress Admin, navigate to Plugins → Add Plugin.

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

Once installed, click Activate Plugin.

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:

Navigate to Application, then select the Credentials section.
Note down the following:
- App ID
- Region
- REST API Key (from Credentials → REST API Keys)

Configure Plugin Settings

In WordPress Admin, go to Settings → CometChat (or click Settings on the CometChat row under Plugins).
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.
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.

Embed Widget Inline (Embedded Mode)

Edit any Page/Post, add a Shortcode block, and insert:

[cometchat 
  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 -->
]

Publish or update the Page/Post.

Docked Widget (Floating Mode)

Edit any Page/Post (or site-wide), add a Shortcode block, and insert:

[cometchat 
  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 -->
]

Publish or update to see the widget docked on the chosen side.

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

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

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).

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.

The Widget Builder includes a Custom Code tab where you can add Custom CSS (and Custom JS) that ships with your widget. Styling uses the same --cometchat-* CSS variables used across CometChat’s UI Kits, so you can re-theme colors, typography, and spacing without editing the plugin. Open it from the dashboard: Chat & Messaging → Get Started / Integrate → No Code → WordPress → Widget Builder → Custom Code tab. Custom CSS added here is automatically scoped under the widget’s root, so top-level selectors like :root or body won’t match. Target .cometchat-root — which carries the --cometchat-* variables — instead. Example — override the primary color and font:

.cometchat-root {
  --cometchat-primary-color: #6852D6;
  --cometchat-font-family: "Inter", sans-serif;
}

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

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.
JavaScript errors: Check browser console for missing CometChatApp or invalid parameters.

Need Help?

Questions or issues? Contact CometChat Support.

Add CometChat Widget to WordPress via Plugin

Before getting started

Quick Steps to Embed CometChat Widget

Advanced JavaScript APIs

Open a chat or start a call

Listen for widget events

Change the widget language

Anonymous & guest access

Customize the widget with CSS

Troubleshooting

Need Help?

​Before getting started

​Quick Steps to Embed CometChat Widget

​Advanced JavaScript APIs

​Open a chat or start a call

​Listen for widget events

​Change the widget language

​Anonymous & guest access

​Customize the widget with CSS

​Troubleshooting

​Need Help?

Before getting started

Quick Steps to Embed CometChat Widget

Advanced JavaScript APIs

Open a chat or start a call

Listen for widget events

Change the widget language

Anonymous & guest access

Customize the widget with CSS

Troubleshooting

Need Help?