> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/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.

> [!WARNING]
>
> **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](https://www.cometchat.com/docs/widget/migration) before you switch.

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

**1. Download the Plugin ZIP**

1. Download the CometChat plugin from [here](https://kernl.us/api/v1/archive/6acf14b8c5ae6e397f441ecc).
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](https://mintcdn.com/cometchat-22654f5b/T-kVUXtubs0NtFU5/images/chat-widget-wordpress-1.png?fit=max\&auto=format\&n=T-kVUXtubs0NtFU5\&q=85\&s=4d38f07532575af5a6dc3c8e968f62e6)

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

![Main dashboard interface](https://mintcdn.com/cometchat-22654f5b/T-kVUXtubs0NtFU5/images/chat-widget-wordpress-2.png?fit=max\&auto=format\&n=T-kVUXtubs0NtFU5\&q=85\&s=7ec134f51d6cf969b28e3453f6c9cb87)

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

![Main dashboard interface](https://mintcdn.com/cometchat-22654f5b/T-kVUXtubs0NtFU5/images/chat-widget-wordpress-3.png?fit=max\&auto=format\&n=T-kVUXtubs0NtFU5\&q=85\&s=95ab1fe38b58390d8226a5ed1f990f51)

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

> [!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.

**5. Embed Widget Inline (Embedded Mode)**

1. Edit any Page/Post, add a **Shortcode** block, and insert:
   ```text theme={null}
   [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.

> [!NOTE]
>
> **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:
   ```text theme={null}
   [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.

> [!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.

***

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

```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](https://www.cometchat.com/docs/widget/html/overview.md) 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.

> [!NOTE]
>
> 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:

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.