Skip to main content
The Circuit chat widget lets website visitors talk to one of your agents without signing in to Circuit. Paste one script tag into your page, and Circuit renders a launcher bubble in a corner of your site. Clicking the bubble opens a chat interface inside an iframe.

​
How it works

  1. Your page loads launcher.js from chat-embed.circuit.ai. The launcher is a small (~2 KB) script that reads the apiKey from its own <script src> URL.
  2. The launcher fetches GET /chat-bot/config from the Circuit API using the key. This call returns the agent’s name, branding, and feature settings. If the call fails for any reason, the launcher logs a warning and renders nothing.
  3. On success, the launcher renders a fixed-position bubble (64×64 px, z-index: 2147483647) using the branding from the config.
  4. When a visitor clicks the bubble, the launcher injects an <iframe> pointing to chat-embed.circuit.ai/embed?apiKey=…. The iframe hosts the chat SPA.
  5. The launcher and SPA communicate using versioned postMessage envelopes ({ version: 1, type, payload }). The launcher forwards the config to the SPA after the SPA signals it is ready.
Visitors are anonymous. The widget does not identify visitors or require a login.

​
What you need

  • A configured agent whose reference scope covers the content you want visitors to ask about.
  • An agent API key, created on the agent’s Chatbot settings page.
  • The hostname of every site that will embed the widget, added to the key’s Allowed Website Domains list. Requests from any other origin are rejected with 403.
Setup takes a few minutes. Follow the quickstart.

​
Current limitations

The widget does not currently support:
  • Identifying signed-in visitors or passing user attributes to the agent.
  • File uploads from visitors.
  • More than one agent per widget, or more than one widget per page.
  • Custom fonts, custom CSS, or hiding built-in controls.
If your use case needs capabilities beyond what the widget supports, contact the Circuit team.

​
Learn more

Quickstart

Create a key, allow your domains, and add the script tag.

Configuration

Branding, position, welcome message, and other settings.

Security

Everything a security review needs: sessions, CSP, domains, and rate limits.

Troubleshooting

Fixes for the most common setup problems.