ChatMadi

Troubleshooting Guide

  • Use this as a checklist when something doesn’t look right. Each section links to Install, Dashboard, and key API endpoints for quick tests.
  • Prefer running the smoke tests in § Smoke tests to isolate whether an issue is your site, network, or configuration.

A) Bubble does not appear

Bubble does not appear

  1. Confirm the snippet is pasted in the right place. Paste the embed from Install just before </body>. If using a builder (WordPress/Webflow/Wix/Squarespace/Shopify/GTM), follow the platform note on the Install ▸ Platforms section exactly—many editors have separate footer fields.
  2. Verify the correct Widget ID. The copied code must include your active ID from Widget settings. Re-copy to avoid typos or trailing spaces. If you have multiple sites, ensure each one uses its own ID.
  3. Check browser DevTools ▸ Network. Reload and confirm /api/widget.js?wid=… returns 200. If blocked or 404, the path is wrong or a proxy is interfering. If your CSP is strict, see § CSP / CORS.
  4. Rule out extensions and ad blockers. Try an incognito window with extensions off. Some blockers hide any “chat” UI. If it appears in incognito, advise visitors to allowlist or use a safer name for the container element (advanced).
  5. Resolve z-index or overlay conflicts. If the bubble exists but sits behind other UI, add a tiny override on your site:
    /* Optional site-side fix */
#chatmadi-bubble-container { position: fixed !important; z-index: 2147483000 !important; }
  6. Single Page Apps (React/Vue/Next/Nuxt). Paste the snippet outside your framework’s root so reloads don’t duplicate/destroy the node. If using SSR (Next.js), keep it in the HTML body, not inside a component that re-renders on each route.
  7. GTM users. Use a “Custom HTML” tag, trigger on All Pages, and ensure Consent settings allow “ad_storage=granted” if your CMP blocks tags by default. Publish the GTM container after changes.

B) WhatsApp does not open (or opens incorrectly)

WhatsApp does not open

  1. Confirm phone format (E.164). Set your number in Profile using full international format (e.g., +91XXXXXXXXXX). Missing the + or country code will break the deep link.
  2. Desktop vs. mobile behavior. Desktop opens WhatsApp Web; mobile opens the app. If WhatsApp Web is disabled by a firewall or company policy, the link may appear unresponsive—try a mobile device.
  3. Popup or navigation blockers. iOS Safari may block if the user interaction is unclear. Keep the open action bound to a direct click (the default bubble is fine).
  4. Prefill message issues. Remove special characters to rule out encoding problems. Keep it short; long prefill messages can be truncated by the OS/app.
  5. Multiple numbers or overrides. If you pass a number via data attributes or a custom button, verify it matches your canonical format in Profile.

C) Auto-trigger doesn’t fire

Auto-trigger doesn’t fire

  1. Include the optional snippet. Copy the Auto-trigger block from Install ▸ Auto-trigger. Without it, the chat never opens automatically.
  2. Start gently. Use a clear rule (e.g., “open after 10s on home”). Aggressive rules on every page can be suppressed by browsers or annoy users; measure impact in Analytics.
  3. Console check. Open DevTools ▸ Console to confirm no JavaScript errors block execution.

D) Wrong message chosen (greeting vs off-hours, or wrong language)

Wrong message chosen

  1. Validate with the API first. Open Templates QA and click the open link in any row to see /api/templates/choose results. This shows decision details: time zone, on/off hours, and chosen locale.
  2. Business hours set correctly? In Business hours, set Mon–Sat windows, closed days, and the proper time zone. To simulate quickly, add h/m and inline hours in the URL (example pattern): ?wid=…&locale=en&h=11&m=15&mon=10:00-18:00&sun=closed.
  3. Locale fallback unexpected? Ensure you actually have templates for the requested language under Templates. If missing, the system falls back to English/default. Use Manage kinds for any custom types.
  4. Message still wrong? Re-run the QA with “Include inline business hours” enabled to rule out hours storage issues and compare the API response.

E) Analytics show zeros (or fewer events than expected)

Analytics zeros

  1. Confirm the widget actually loaded. If /api/widget.js didn’t run, no events will be sent. Revisit Install and § Bubble does not appear.
  2. DevTools ▸ Network. Trigger the chat and verify POST /api/analytics returns 200. If blocked by ad/cookie consent tools, allow this endpoint and republish your settings.
  3. Self-hosting only (advanced). If you deployed your own backend and see 500s, check environment variables and DB permissions. A missing service role or incorrect table/column names will prevent writes.
  4. Cross-check with a smoke test. See § Smoke tests. If the API accepts events but the dashboard stays empty, confirm the correct Widget ID is selected on Analytics.

F) Layout, overlap, or visibility issues

Layout issues

  1. Move the bubble. Switch left/right in Widget settings to avoid language pickers, cookie banners, or “back to top” buttons.
  2. Raise z-index. If other sticky elements cover the bubble, apply a CSS override as shown in § A.5.
  3. Mobile safe area. On devices with home indicator bars, verify the bubble sits above the safe area; the script handles this by default, but test on a tall page and on iOS/Android.

G) Performance considerations

Performance

  1. Async by default. The loader is tiny and async; it won’t block rendering. If you see a delay, check for duplicate snippets or third-party conflicts.
  2. Avoid duplicates. Ensure the snippet is included exactly once (GTM + hardcoded can double load). Use DevTools ▸ Elements to confirm a single container node.

H) Platform-specific notes (quick checks)

Platform specifics

  1. WordPress. Use a footer injection plugin or your theme’s “Footer Scripts”. Don’t paste inside the post editor. Clear caches (plugin/CDN) after publishing.
  2. Webflow. Project Settings ▸ Custom Code ▸ Footer Code. Publish to the domain, not just staging.
  3. Wix / Squarespace. Use the global footer/custom code area. Some plans restrict custom HTML— upgrade if the field is missing.
  4. Shopify. theme.liquid, paste before </body>. If using a theme app block, confirm it loads across templates.
  5. React / Next / Vue / Nuxt. Put the snippet in the HTML shell (e.g., Next’s app/root layout <body>) rather than inside a component that re-renders per route.
  6. GTM. Custom HTML tag, All Pages trigger, publish container, and ensure consent doesn’t suppress the tag.

I) Content-Security-Policy (CSP) & CORS

CSP & CORS

  1. Minimal directives (example). If you use a strict CSP, allow the loader and API:
    script-src 'self' chatmadi.com;
connect-src 'self' chatmadi.com;
img-src 'self' data:;
style-src 'self' 'unsafe-inline'; /* if your site already allows inline styles */
    Adjust the domain(s) based on your deployment. If a policy blocks the script, the bubble won’t render.
  2. CORS errors in console? These usually indicate a proxy/CDN rewrite. Ensure requests to/api/widget.js, /api/analytics, and /api/track-lead pass through untouched.

J) Leads & webhooks

Leads & webhooks

  1. Leads appear but webhook not firing? Recheck the webhook URL in your integration page (if enabled). The receiver must return 2xx. Use a request bin to confirm deliveries.
  2. No leads at all? Ensure your pre-chat is enabled and minimal (name + message). Heavy forms reduce completion. See Profile for number format and Widget settings for pre-chat toggles.

K) Common HTTP/API errors & quick fixes

HTTP errors

  1. 400 Bad Request. Usually missing wid or invalid params on /api/templates/choose. Rebuild the URL from Templates QA to copy a known-good pattern.
  2. 403/404. Path or domain mismatch. Confirm you’re calling the correct host and route. CDNs can rewrite /api/*—allow these paths.
  3. 429 Too Many Requests. Back off your QA scripts; add small delays between calls.
  4. 5xx. Temporary backend error or custom deployment misconfig. Retry and check § Smoke tests.

L) Smoke tests (copy, run, verify)

Smoke tests

  1. Analytics event. Open this in your browser console (adjust WID):
    fetch('/api/analytics', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ wid: '<WID>', event: 'widget_view', meta: { referrer: location.href } })
}).then(r => r.json()).then(console.log).catch(console.error);
    Then check Analytics to see the count rise.
  2. Track a lead (quick). Use a minimal payload to ensure writes succeed:
    fetch('/api/track-lead?wid=<WID>', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ name: 'QA Test', message: 'Hello from Troubleshooting page', source: 'docs-smoke' })
}).then(r => r.json()).then(console.log).catch(console.error);
  3. Choose API (greeting vs off-hours). Replace <WID> and try both links:
    /api/templates/choose?wid=<WID>&locale=en&h=11&m=15&mon=10:00-18:00&sun=closed
    /api/templates/choose?wid=<WID>&locale=en&h=23&m=30
    Expect kind=greeting at 11:15 (business hours) and kind=off_hours at 23:30.

M) Still stuck? Share exact details for fastest help

Still stuck

  1. Include these in your message: site URL, your Widget ID (last 6 chars), what you expected, what you saw, browser + device, and any console/network screenshots (/api/widget.js, /api/analytics, /api/track-lead, /api/templates/choose).
  2. Link the relevant doc section. For example, “Issue matches § A and § I” so we can jump straight to likely causes.