> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-js-sdk-llms-index.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 **REST API 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-docs-js-sdk-llms-index/fBs11D0rY0iBI1Kg/images/chat-widget-wordpress-1.png?fit=max&auto=format&n=fBs11D0rY0iBI1Kg&q=85&s=dc35f2e83f3b37d74b6ac5cab3fb46e5" 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-docs-js-sdk-llms-index/fBs11D0rY0iBI1Kg/images/chat-widget-wordpress-2.png?fit=max&auto=format&n=fBs11D0rY0iBI1Kg&q=85&s=353cc8ac6ada7d1c696975f37bd3ee39" 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-docs-js-sdk-llms-index/fBs11D0rY0iBI1Kg/images/chat-widget-wordpress-3.png?fit=max&auto=format&n=fBs11D0rY0iBI1Kg&q=85&s=1399b15538bca77d6c5c93d8ee26d6fa" 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:

       * **App ID**
       * **Region**
       * **REST API Key** (from **Credentials → REST API Keys**)
  </Step>

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

    <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 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.
    </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">
    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.

    <Note>
      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.
    </Note>
  </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 — 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](/widget/html/overview) 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. 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:

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