> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-ketanyekale-eng-37952-docs-gap-wordpress.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Add CometChat Widget to WordPress via Plugin

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

## Before getting started

Go through the [Overview](https://app.cometchat.com/) 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

<Steps>
  <Step title="Download the Plugin ZIP">
    1. Download the CometChat plugin from [here](https://kernl.us/api/v1/archive/688bbf1f5a0dc110ce1bfafe).
    2. Save the `cometchat-pro.zip` file to your computer.
  </Step>

  <Step title="Install & Activate the Plugin">
    1. In WordPress Admin, navigate to **Plugins → Add Plugin**.

    <img src="https://mintcdn.com/cometchat-22654f5b-ketanyekale-eng-37952-docs-gap-wordpress/TOdXiUiDlccWdiXZ/images/chat-widget-wordpress-1.png?fit=max&auto=format&n=TOdXiUiDlccWdiXZ&q=85&s=e8b91bfc941e055b0c0435a2b53f2b7d" alt="Main dashboard interface" height="300" className="rounded-lg" data-path="images/chat-widget-wordpress-1.png" />

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

    <img src="https://mintcdn.com/cometchat-22654f5b-ketanyekale-eng-37952-docs-gap-wordpress/TOdXiUiDlccWdiXZ/images/chat-widget-wordpress-2.png?fit=max&auto=format&n=TOdXiUiDlccWdiXZ&q=85&s=8d6e9ffd06e54bb8d9eabc7dad7a4a86" alt="Main dashboard interface" height="300" className="rounded-lg" data-path="images/chat-widget-wordpress-2.png" />

    3. Once installed, click **Activate Plugin**.

    <img src="https://mintcdn.com/cometchat-22654f5b-ketanyekale-eng-37952-docs-gap-wordpress/TOdXiUiDlccWdiXZ/images/chat-widget-wordpress-3.png?fit=max&auto=format&n=TOdXiUiDlccWdiXZ&q=85&s=55a600780396ee9674c04a9c3b86df50" alt="Main dashboard interface" height="300" className="rounded-lg" data-path="images/chat-widget-wordpress-3.png" />
  </Step>

  <Step title="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**
  </Step>

  <Step title="Configure Plugin Settings">
    1. In WordPress Admin, open the **CometChat** plugin settings (added after you activate the plugin).
    2. Paste your **Widget ID**, **App ID**, **Region**, and **Auth Key**, then click **Save Changes**.

    <Note>
      **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 (UID) and signs them in with a securely generated auth token; you do **not** configure a fixed user UID in the plugin. Where the widget appears (inline vs. floating) is set per placement by the shortcode's `docked` attribute, shown below.
    </Note>
  </Step>

  <Step title="Embed Widget Inline (Embedded Mode)">
    1. Edit any Page/Post, add a **Shortcode** block, and insert:
       ```text theme={null}
       [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.
  </Step>

  <Step title="Docked Widget (Floating Mode)">
    1. Edit any Page/Post (or site-wide), add a **Shortcode** block, and insert:
       ```text theme={null}
       [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.
  </Step>

  <Step title="Show the Docked Widget on Every Page">
    Add the docked shortcode (`docked="true"`) to a template that renders on every page — for example a site-wide footer, a **Custom HTML** block in a global widget area, or your theme's footer template. The floating bubble will then appear across your public pages (for logged-in WordPress users).
  </Step>
</Steps>

***

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

```js theme={null}
// 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.

```js theme={null}
// 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.

```js theme={null}
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 by default.

* **Member sites:** no extra setup — your existing WordPress login is the gate, and the plugin authenticates each signed-in member automatically.
* **Guest / anonymous chat:** provide a WordPress-side guest sign-in so the visitor becomes a logged-in WordPress user (for example, sign the visitor into a shared guest account on page load). The plugin then maps that guest to a CometChat UID and authenticates them like any other user.

***

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

Example — override the primary color and font:

```css theme={null}
: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](https://www.cometchat.com/contact).