Live Chat System Troubleshooting

Common issues and quick fixes for the Live Chat widget and chat conversations.

---

Widget issues

Widget not loading

Symptoms

• The widget button doesn’t appear
• You see 403 Domain not authorized or auth errors in the console/network tab
• The script loads but nothing renders

Things to check

1. Embed snippet

Make sure you’re using the current embed approach:

<script type="module">
  import { renderWebWidget } from "https://app.autoch.at/web-widget.js";
  renderWebWidget({
    tenantId: "your-tenant-id",
    apiUrl: "https://api.yourdomain.com",
    token: "your-widget-token",
  });
</script>

2. Token validity

• Widget tokens are signed and expire (default: 30 days). Generate a fresh token if yours is old.

3. Content Security Policy (CSP)

• If your site sends a Content-Security-Policy header (or meta tag), the browser will block the widget script unless your script-src allows it.
• Error you may see: Refused to load https://app.autoch.at/web-widget.js because it does not appear in the script-src directive of the Content Security Policy.
• Fix: Add https://app.autoch.at to your script-src directive. Example:
  script-src 'self' https://app.autoch.at;
  (Adjust to match your existing policy; you may also need connect-src for the widget’s API calls if they go to a different origin.)

4. Domain allowlist (if enabled)

• If your tenant uses a widget domain allowlist, confirm your site’s domain is included.
• A missing/incorrect domain will typically show up as 403 responses from widget endpoints.

5. API reachability

• Verify the apiUrl is correct and reachable from the customer’s browser.

---

Widget not sending messages

Symptoms

• You can type, but sending fails
• You get an error toast in the widget
• The request returns 401, 403, 429, or 500

Quick test

curl -X POST https://api.yourdomain.com/api/widgets/your-tenant-id/chat \
  -H "Authorization: Bearer your-widget-token" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"test_session","message":"Hello!"}'

Common causes

• Missing/expired widget token (401)
• Domain not authorized (403)
• Usage limits hit (429)
• No default chat assistant configured for the tenant (400/500, depending on tenant setup)

---

Dashboard real-time issues (WebSocket)

The widget chat flow uses HTTP. WebSockets are primarily for keeping the dashboard in sync across tabs and teammates.

Real-time updates not working in the dashboard

Symptoms

• New conversations/messages don’t appear until refresh
• Connection errors in the console

What to check

• WebSocket connection to wss://api.yourdomain.com/api/ws/tenant succeeds
• You send the JWT auth message within 5 seconds
• Your JWT is valid and not expired

See: WebSocket Integration

---

AI response issues

No AI responses (or responses seem blocked)

Symptoms

• The widget request succeeds, but the assistant doesn’t reply
• Replies get flagged/held for review (depending on tenant settings)

What to check

• A default assistant is configured for chat (or routing rules map chat to an assistant).
• Your AI provider is configured (e.g., OpenAI key / BYOK configuration, depending on your tenant).
• Safety settings aren’t blocking the response (serious-mode triggers, blocked keywords, escalation rules).
• Rate limits aren’t being hit during busy periods.

---

Widget tracking analytics issues

Guided Snippet Builder not visible

What to check

1. If Guided Snippet Builder was disabled via Grain, set widget_tracking_snippet_builder_enabled to true (or remove the key; it defaults to enabled).
2. Confirm you are on Settings -> Chat Widget -> Tracking (/settings/widget?tab=tracking).
3. If you are a platform/system admin and the feature is publicly closed, look for the gate banner (admin bypass state).

If builder access is closed, static templates and Widget Tracking Health remain available by design.

"Preset registry unavailable" notice appears

This means preset metadata fetch failed and UI switched to built-in defaults.

Expected behavior

1. Guided builder still works with deterministic local defaults.
2. Static template cards and diagnostics continue to work.
3. You can continue with copy/install while backend preset endpoint is recovered.

No tracking events on the host page

What to check

1. Confirm browser events are wired:
   • autochat.widget_tracking.v1
   • canonical alias events (for example autochat.lead_qualified.v1)
2. Confirm your mapping has emit_browser = true.
3. Confirm the conversation source is eligible chat widget traffic (not websocket dashboard stream).

Canonical alias event not firing

The stable event (autochat.widget_tracking.v1) should always be your primary trigger in GTM. Alias events are convenience events and depend on the specific canonical outcome emitted.

High webhook fail-rate warning in Widget Tracking Health

Use Settings → Chat Widget → Tracking → Widget Tracking Health and inspect:

1. By-event-type failures
2. Recent failure rows (redacted error summary + status code)
3. 15-minute warning threshold (>=10 attempts and >=10% failures)

If failures persist, verify your tenant webhook endpoint availability, signature validation, and response timing.

---

Still stuck?

If you send us:

• The failing endpoint + status code
• Your tenant ID (and the request ID if available)
• A short description of what you expected vs what happened

…we can usually pinpoint the issue quickly.