Skip to main content

​
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 Auth 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.
Main dashboard interface
  1. Click Upload Plugin, choose cometchat-pro.zip, and click Install Now.
Main dashboard interface
  1. Once installed, click Activate Plugin.
Main dashboard interface
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 keys:
    • App ID
    • Auth Key
    • Region
4

Configure Plugin Settings

  1. In WordPress Admin, go to CometChat UI Kit Builder in the sidebar.
  2. Paste your Widget ID, App ID, Region, and Auth Key.
  3. (Optional) Set Default User UID to auto-login a specific user.
  4. Choose Display Mode:
    • Embedded (inline on specific pages)
    • Docked (floating on every page)
  5. Click Save Changes.
5

Embed Widget Inline (Embedded Mode)

  1. 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 -->
]
  2. Publish or update the Page/Post.
6

Docked Widget (Floating Mode)

  1. 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 -->
]
  2. Publish or update to see the widget docked on the chosen side.
7

Enable Docked on All Pages

  1. In CometChat UI Kit Builder settings, set Display Mode to Docked.
  2. Save—widget will now float on every public page.

​
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 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
LanguageCode
English (United States)en-US
English (United Kingdom)en-GB
Dutchnl
Frenchfr
Germande
Hindihi
Italianit
Japaneseja
Koreanko
Portuguesept
Russianru
Spanishes
Turkishtr
Chinese (Simplified)zh
Chinese (Traditional)zh-TW
Malayms
Swedishsv
Lithuanianlt
Hungarianhu
Need another locale? Use the same pattern with its code (for example CometChatApp.localize("ko") for Korean).

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