docs(widget/wordpress): align integration & overview with the shipped plugin

[ketanyekale]

What & why

Addresses ENG-37952 (AgentBuddy DOCUMENTATION_GAP, ticket #45163, appears in both the Jul 15–22 and Jul 21–28 tabs). The WordPress widget docs described a plugin UI that doesn't match what ships, which led an AI agent to answer a support ticket incorrectly end-to-end.

Changes

integration.mdx

• Removed the non-existent "CometChat UI Kit Builder" sidebar item, "Default User UID" field, and plugin-level "Display Mode" setting from Configure Plugin Settings.
• Documented the real auth model: the widget is gated by WordPress's is_user_logged_in(), and the plugin auto-maps each logged-in WP user to a CometChat UID with a securely generated auth token (no fixed UID in the plugin).
• Docked vs. embedded is driven by the shortcode docked attribute; reworked the "every page" step to use the shortcode instead of a Display Mode setting.
• Added Anonymous & guest access guidance and a Customize the widget with CSS section (Widget Builder → Custom Code tab, --cometchat-* variables) with the correct dashboard nav path.

overview.mdx

• Fixed button label "Get Embedded Code" → "Get Embed Code".
• Added a short Customization pointer to the new CSS section.

⚠️ Reviewer verification needed (treated the L2/sheet findings as source of truth)

I don't have the shipped plugin source, so please confirm these before merge:

1. Real plugin settings location/label — I replaced "CometChat UI Kit Builder in the sidebar" with a neutral "open the CometChat plugin settings." Please set the exact WP admin menu label.
2. is_user_logged_in() gate + auto UID mapping + auto auth-token — stated per L2; confirm wording matches plugin behavior.
3. Guest access recipe — described at a high level (WP-side guest sign-in); confirm the recommended approach.
4. "Get Embed Code" label — the old "Get Embedded Code" string is still used in 12 other files (all other widget platforms + snippets/widget/overview.mdx + several ai-agents/* pages). If the real button is "Get Embed Code", those should be updated in a follow-up; I scoped this PR to the WordPress ticket only.
5. --cometchat-* example values — the two variables shown are illustrative; confirm the canonical widget theming variables.

Fixes ENG-37952

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cometchat	🟢 Ready	View Preview	Aug 4, 2026, 6:00 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[birendraprasad-gupta]

Review — verified against the shipped plugin source

How I verified this (sources)

Since the whole point of this PR is "does the doc match what ships", I didn't review it against the L2 sheet — I reviewed it against the code. Two sources:

1. The shipped WordPress plugin. Downloaded from the exact Kernl link printed in this doc at widget/wordpress/integration.mdx:22 — https://kernl.us/api/v1/archive/688bbf1f5a0dc110ce1bfafe → cometchat-pro v0.0.14 (cometchat-pro.php:6). Read all four source files: cometchat-pro.php, includes/settings.php, includes/shortcode.php, includes/sync.php.
2. The widget the plugin loads. @cometchat/chat-embed v1.0.36 (visual-chat-builder-app), which is what shortcode.php:84 pulls from jsDelivr at runtime.

Every claim below cites a file and line so it can be checked independently. Anything I could not verify from source, I've marked as such rather than asserting it.

---

Verdict

The direction is right — "CometChat UI Kit Builder", "Default User UID" and plugin-level "Display Mode" genuinely do not exist anywhere in the plugin, so removing them is correct and this PR is a real improvement.

But I'd hold the merge. Two of the newly-added statements are inaccurate, one replaces a working plugin feature with harder manual work, and the single biggest remaining error in the file — the credentials list — isn't touched by this PR.

---

Answers to the 5 verification items

1. Plugin settings location → Settings → CometChat

cometchat-pro.php:46 registers it with add_options_page('CometChat', 'CometChat', 'manage_options', 'cometchat-pro/includes/settings.php', ...), and there's a Settings link added to the plugin's row on the Plugins page. So it lives under Settings, not as a top-level sidebar item. The neutral wording in this PR is safe but vague — we can state it exactly now.

2. is_user_logged_in() gate, auto UID mapping, auto auth token → CONFIRMED, with two corrections

• Gate confirmed at shortcode.php:8.
• It does not hide silently — shortcode.php:9 returns literal visible text: <div id="cometchat">Please login to use this feature.</div>. Worth documenting, users will see this string.
• The CometChat UID is the WordPress numeric user ID, not the username — shortcode.php:13 ($uid = $current_user->ID).
• Token flow confirmed: sync.php:60 creates the user with withAuthToken: true, sync.php:88-100 validates/regenerates via users/{id}/auth_tokens/, using the REST API key server-side (sync.php:254). The frontend then inits with "authKey": "dummy" (shortcode.php:201) and logs in with the token. The security framing in the new Note is accurate — no real key reaches the browser.

3. Guest access recipe → please replace this

The suggested approach (sign the visitor into a shared guest account on page load) means a shared credential for strangers, session/nonce complications, and it defeats full-page caching. I'd rather not recommend that in writing.

The plugin has no guest path and no filter hook to add one — shortcode.php:8 is an unconditional early return. But the embed script itself supports guest mode natively: src/CometChatNoCode/auth/cometchat-auth.ts accepts mode: 'guest' | 'uid' | 'authToken' and auto-creates a guest UID. It's simply not exposed through the plugin.

Suggested honest framing: anonymous chat is not supported by the WordPress plugin today; use the HTML/JS embed with mode: "guest" on pages that need it.

4. "Get Embed Code" label — could not verify. That's dashboard UI, not in either repo I read. Scoping it to this PR is defensible, but a label fix landing in 1 of 13 files creates a fresh inconsistency. I'd either drop it here or do the 13-file sweep in one commit.

5. --cometchat-* values are real, but the example does not work

Both --cometchat-primary-color and --cometchat-font-family exist in the widget. The problem is the selector.

src/CometChatNoCode/customHooks/useInjectNoCodeStyles.ts (scopeCssToSelector) rewrites every top-level selector in Custom CSS to .CometChatApp <selector> before injecting it. So the documented snippet becomes:

.CometChatApp :root { --cometchat-primary-color: #6852D6; }

:root is the <html> element and can never be a descendant of .CometChatApp, so this matches nothing. Copy-paste the snippet as documented and literally nothing happens.

The working target is .cometchat-root (rendered inside .CometChatApp — see CometChatHome.tsx:2224):

.cometchat-root {
  --cometchat-primary-color: #6852D6;
  --cometchat-font-family: "Inter", sans-serif;
}

Please smoke-test this in the builder before merge — generateExtendedColors() reads the computed primary color to derive the extended palette, and I can't tell from static reading whether it re-runs after injection.

---

Not covered by this PR, but higher impact

A. The credentials list is still wrong — lines 15 and 74

Line 74 still says "Paste your Widget ID, App ID, Region, and Auth Key". The actual settings screen (includes/settings.php) has exactly four fields:

Field	Source line	Notes
App ID	settings.php:46
App Region	settings.php:58	dropdown US / EU / IN
API Version	settings.php:75	dropdown 3 / 2 (Legacy)
Rest API Key	settings.php:95	Dashboard → App → Credentials → Rest API Keys

There is no Widget ID field and no Auth Key field. The plugin never uses an Auth Key — it authenticates to the REST API with the REST API key as the apiKey header (sync.php:254). Variant/Widget ID belongs in the shortcode's variant-id. Line 15 ("Your App ID, Region, and Auth Key") has the same problem.

This is a customer-blocking error and I suspect it's closer to the root of the original ticket than the items this PR fixes.

B. API Version must be set to 3 — completely undocumented, silently breaks setup

sync.php:244 falls back to "2" when the option is empty, and builds https://api-{region}.cometchat.io/v2.0/.... A fresh install where nobody touches that dropdown therefore hits the legacy v2 API: user creation fails, no auth token is stored, and shortcode.php renders "Authentication failed. Please try again." with no explanation. This deserves an explicit step.

C. The "every page" rewrite replaces a real feature with theme editing

The old text was wrong, but the replacement points users at their theme's footer template. The plugin already ships the feature: settings.php:107 is a textarea labelled "Load CometChat on all pages/sitewide?", saved as cometchat_pro_footer (cometchat-pro.php:67-73) and rendered via add_action('wp_footer', ...) (cometchat-pro.php:96-100).

Suggested replacement for that step:

In Settings → CometChat, paste your docked shortcode into "Load CometChat on all pages/sitewide?" and click Update Settings. The widget then renders in the footer of every page.

Note: for logged-out visitors this prints "Please login to use this feature." sitewide — leave it blank or hide #cometchat via CSS if that isn't wanted.

D. Shortcode attribute values are aggressively sanitized

removeAllQuotes() (shortcode.php:237-244) strips every character outside [a-zA-Z0-9%-] from all attribute values (shortcode.php:59). So the documented example default-chat-id="uid_or_guid" is silently rewritten to uidorguid and points at the wrong chat. Any UID or GUID containing _, . or @ is affected — which is most of them. Same applies to the undocumented default-username attribute.

Worth a warning box here, plus a ticket for the plugin team.

E. Minor

• The <!-- ... --> annotations inside the shortcode code blocks are copy-paste hostile — better as a table under the snippet.
• variant-id="default-variant" reads like a real default value; mark it clearly as a placeholder.
• The save button is labelled Update Settings (settings.php:119), not "Save Changes".
• shortcode.php:84 loads @cometchat/chat-embed@latest unpinned from jsDelivr. Not a docs bug, but it explains "my widget changed overnight" tickets and may be worth a note.
• Both [cometchat] and [cometchat-pro] are registered (shortcode.php:246-247); legacy widget-id / widget-version attributes are still supported. Fine to leave undocumented, just noting it.

---

Suggested rewrite of the Configure step

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** — 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** — Dashboard → App → Credentials → Rest API Keys.
     This is the REST API key, not the Auth Key.
3. Click **Update Settings**.

---

One process note

The PR description says the L2/sheet findings were treated as source of truth because the plugin source wasn't available. Two of those findings didn't survive contact with the code — the guest recipe, and the implied absence of a sitewide setting. The plugin ZIP is one curl away from a link that's already printed in this very document (line 22). For the next DOCUMENTATION_GAP fix, reading the plugin first is cheap and would have caught the credentials error too.

Happy to pair on the follow-up edits if useful.

[birendraprasad-gupta]

Inline notes to go with my summary comment above, now re-checked against 2784f04 ("Replaced Widget ID -> Variant ID").

One correction to my earlier comment: it quoted line 74 as "Widget ID", which was the text at 431c8b3. 2784f04 changed it to "Variant ID". The underlying issue is unchanged — see the inline note on that line — but I was quoting stale text and wanted to flag that rather than leave it.

Same sources as before: plugin cometchat-pro v0.0.14 (downloaded from the Kernl link at line 22 of this doc) and @cometchat/chat-embed v1.0.36.