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

## 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/T-kVUXtubs0NtFU5/images/chat-widget-wordpress-1.png?fit=max&auto=format&n=T-kVUXtubs0NtFU5&q=85&s=4d38f07532575af5a6dc3c8e968f62e6" 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/T-kVUXtubs0NtFU5/images/chat-widget-wordpress-2.png?fit=max&auto=format&n=T-kVUXtubs0NtFU5&q=85&s=7ec134f51d6cf969b28e3453f6c9cb87" 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/T-kVUXtubs0NtFU5/images/chat-widget-wordpress-3.png?fit=max&auto=format&n=T-kVUXtubs0NtFU5&q=85&s=95ab1fe38b58390d8226a5ed1f990f51" 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, 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**.
  </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="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.
  </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).

***

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