Skip to main content
Work through the symptom that matches what you see. Most problems surface in the browser’s developer console, so open it first (F12 in most browsers, then the Console and Network tabs).

​
Bubble does not appear

Console shows a console.warn about the chatbot config. The launcher fetches GET /chat-bot/config on page load. If that call fails for any reason (network error, non-2xx response, malformed JSON, missing or revoked key), the launcher logs a warning and renders nothing. Check:
  • The script tag’s src ends with ?apiKey=YOUR_AGENT_KEY.
  • The key has not been revoked in the agent’s Chatbot settings.
  • There are no network errors on the config request in the Network tab.
Console shows a CSP violation for script-src. Your site’s Content Security Policy is blocking the launcher script. Add https://chat-embed.circuit.ai to your script-src directive. See Content Security Policy. No console errors and no bubble. Confirm the script tag is present in the served HTML (use View Source, not the DOM inspector) and that a request for launcher.js appears in the Network tab. Tag managers and CMS custom-code fields sometimes strip script tags or apply them only to certain pages.

​
Messages fail with 403 origin not allowed

The page’s hostname is not on the API key’s Allowed Website Domains list. In the agent’s Chatbot settings, open the key and add the exact hostname shown in your browser’s address bar. Rules:
  • example.com and www.example.com are different entries. Add both if you serve from both.
  • Enter hostnames only, without https:// or a port number.
  • Staging and localhost hostnames need their own entries.
The check fails closed: a key with an empty allowed domains list rejects every request. See domain allowlisting.

​
Messages fail with 401

The key is missing, wrong, or has been revoked. Create a new key in the agent’s Chatbot settings, update the src in the script tag, and hard-reload the page.

​
Messages fail with 429

The key has exceeded 60 requests per minute, counted across all visitors using that key. The X-RateLimit-Reset response header shows when the window resets. If normal traffic reaches this limit, contact the Circuit team.

​
CSP violation on frame-src

The launcher injects an <iframe> pointing to chat-embed.circuit.ai. Add https://chat-embed.circuit.ai to your frame-src directive. The launcher script and the iframe share the same origin, so the same host covers both.

​
Conversation resets between page loads or messages

The SPA stores the session token in localStorage. If localStorage is blocked (strict browser privacy settings, extensions, or private browsing mode), the widget still works but each page load or, in some configurations, each message starts a new chat. This is expected behavior in those environments. Sessions also expire after 24 hours regardless of browser settings.

​
Widget hidden behind page elements

The bubble and iframe render at z-index: 2147483647, the maximum CSS integer value. Only host-page elements with a stacking context above this value can cover the widget, which is not possible using a standard z-index value. If your page elements overlap the widget, check for transformed or positioned ancestors with unusually high stacking contexts.

​
Position or color changes do not appear

The config response is cached for 60 seconds. Save your changes in the Chatbot settings, wait up to 60 seconds, and hard-reload the page to bypass the browser cache. See configuration.

​
Still stuck?

Contact the Circuit team with: the page URL, the chatbot key name (never the key value itself), the browser console output, and the failing request’s status code from the Network tab.