Widget doesn't show

Widget isn't showing on your site, or shows only for logged-in users, or shows blank when you open it. This page is the symptom → cause → fix flowchart. Run the checks in order; most installs hit the first one and skip the rest.

Symptom: widget shows for logged-in users only

Cause: page cache. WordPress caching plugins (W3 Total Cache, WP Rocket, LiteSpeed Cache, WP Super Cache), hosting- level page cache (Hostinger, SiteGround, Cloudways, Kinsta), or Cloudflare APO all serve anonymous visitors a cached HTML snapshot taken BEFORE you installed ChatX. Logged-in users bypass page cache, so they always hit fresh PHP and see the widget.

Fix:

1. WP admin → your caching plugin → click Purge All Cache.
2. If you're on Hostinger / SiteGround / Cloudways / Kinsta: control panel → Page Cache → Purge.
3. If Cloudflare is proxying your domain: Cloudflare dashboard → Caching → Configuration → Purge Everything.
4. Open your site in incognito (new private window) → right-click → View Source → search for widget.js. Present = fixed.

Symptom: widget doesn't show at all

Walkthrough:

1. Confirm the ChatX WP plugin is configured. WP admin → ChatX (left sidebar). All three fields must be set: Base URL, API Token, Agent ID. Missing any one of them = the plugin's shouldRender() gate returns false and nothing renders.
2. Confirm the widget is enabled. Same ChatX settings page → checkbox "Widget enabled". Default on, but worth confirming.
3. Confirm post-type scoping. Settings page → "Show on these post types". Defaults to post + page. If your front page is a custom post type (e.g. landing, product) and you haven't ticked it, the widget skips that page. Tick the box.
4. Open browser DevTools → Network tab on your front-end page. Search for widget.js:
   • Present + 200 OK: the script loaded. Check Console for JS errors.
   • Present + 404: your Base URL setting points at a host that doesn't serve widget.js. Should be your ChatX install root (e.g. https://chatx.your-domain.com).
   • Missing entirely: the plugin isn't emitting the tag. Confirm via View Source — look for <script async src=…widget.js…>. Missing tag = the shouldRender() gate failed; re-check the previous 3 items.

Symptom: widget shows but says "Sorry — something went wrong"

Widget retries the SSE stream 3 times then surfaces this generic bubble. The real error is logged server-side; the bubble is intentionally vague so visitors don't see raw provider errors.

Tail your Laravel logs while reproducing in the widget:

tail -f storage/logs/laravel.log

Common patterns and their fixes:

• Workers AI 401: ... — Cloudflare API token rejected. See Cloudflare 401 troubleshooting.
• Vectorize ... expected N dimensions, got M — embed model and index dim mismatch. See Vector dim recovery.
• Workers AI timeout — Cloudflare flaky. Retry; if persistent, switch CLOUDFLARE_CHAT_MODEL to a smaller variant.
• message_quota_exceeded — workspace plan cap reached. Upgrade workspace plan.
• conversation_not_found — widget JWT is older than the conversations.cleared_at on its conversation row. Visitor needs to refresh the page so the widget reissues a fresh JWT via the next /api/v1/widget/init.

Symptom: widget shows but the launcher pill never appears

Theme conflict. Some themes set iframe { display: none !important } or use a global z-index reset. The ChatX widget renders inside a Shadow DOM but its mount point is a <div> on the host page.

Fix: add this CSS to your theme's Additional CSS:

#chatx-root,
#chatx-root * {
    display: revert !important;
    visibility: visible !important;
    z-index: 2147483647 !important;
}

Still stuck?

Reach out at support@chatx.app with:

• One screenshot of the front-end page where the widget isn't showing.
• Output of tail -200 storage/logs/laravel.log (or browser Console output if the script never reached your server).
• The URL of an affected page (if public).