From 431c8b3b10441119f45e8775c88ea9b27800d00c Mon Sep 17 00:00:00 2001 From: "Ketan (CometChat)" Date: Tue, 4 Aug 2026 23:25:59 +0530 Subject: [PATCH] docs(widget/wordpress): align integration & overview with shipped plugin Rewrite the WordPress widget docs to match the plugin's actual behavior (per L2 findings captured in the AgentBuddy review): - Remove the non-existent "CometChat UI Kit Builder" sidebar item, "Default User UID" field, and plugin-level "Display Mode" setting from the Configure Plugin Settings step. - Document the real auth model: the widget is gated by is_user_logged_in() and auto-maps each logged-in WordPress user to a CometChat UID with a securely generated auth token. - Drive docked/embedded display via the shortcode's `docked` attribute (not a Display Mode setting); rework the "every page" step accordingly. - Add "Anonymous & guest access" guidance (WP-side guest sign-in). - Add "Customize the widget with CSS" (Widget Builder Custom Code tab + --cometchat-* CSS variables) with the correct dashboard nav path, and a pointer from overview. - Fix button label "Get Embedded Code" -> "Get Embed Code" in overview. Fixes ENG-37952 Co-Authored-By: Claude Opus 4.8 --- widget/wordpress/integration.mdx | 46 +++++++++++++++++++++++++------- widget/wordpress/overview.mdx | 8 +++++- 2 files changed, 43 insertions(+), 11 deletions(-) diff --git a/widget/wordpress/integration.mdx b/widget/wordpress/integration.mdx index c936c031e..94a039cd6 100644 --- a/widget/wordpress/integration.mdx +++ b/widget/wordpress/integration.mdx @@ -70,13 +70,12 @@ After registering, create a **new app** and retrieve your **authentication detai -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**. +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**. + + +**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. + @@ -110,9 +109,8 @@ After registering, create a **new app** and retrieve your **authentication detai 2. Publish or update to see the widget docked on the chosen side. - -1. In **CometChat UI Kit Builder** settings, set **Display Mode** to **Docked**. -2. Save—widget will now float on every public 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). @@ -123,6 +121,34 @@ After registering, create a **new app** and retrieve your **authentication detai --- +## 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 +: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. diff --git a/widget/wordpress/overview.mdx b/widget/wordpress/overview.mdx index 0a37b9759..773bc9ce7 100644 --- a/widget/wordpress/overview.mdx +++ b/widget/wordpress/overview.mdx @@ -57,7 +57,7 @@ Customize your chat widget using the visual Widget Builder: Once configured, get the embed code snippet for your widget. -1. Click on **Get Embedded Code** +1. Click on **Get Embed Code** 2. Note your app credentials (App ID, Auth Key, Region, Variant ID) 3. Copy the code snippet @@ -80,6 +80,12 @@ Install the CometChat plugin on your WordPress site and go live. --- +## Customization + +The Widget Builder controls theme, colors, and typography with no code. For deeper control, open the Widget Builder's **Custom Code** tab and add your own **Custom CSS** (and Custom JS) using the `--cometchat-*` CSS variables — the same variables used across CometChat's UI Kits. See [Customize the widget with CSS](/widget/wordpress/integration#customize-the-widget-with-css) in the Integration guide. + +--- + ## Try Live Demo Experience the CometChat Widget Builder in action: