> ## Documentation Index
> Fetch the complete documentation index at: https://docs.circuit.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Chat widget quickstart
> Add the Circuit chat widget to your website: create an API key, allow your domains, and paste one script tag.
This guide takes you from nothing to a working chat widget on your site.
## Set up the widget
In Circuit, open the agent you want to embed and go to its Chatbot settings. Create a new chatbot key with a descriptive name, for example "Company website".
The API key is visible in your page's HTML source. The allowed domains list you add in the next step is the control that limits which sites can use it.
In the Allowed Website Domains section, add the hostname of every site that will embed the widget, for example `www.example.com`.
This step is required. The server checks the `Origin` header on every request and rejects any hostname not on the list with 403. A key with an empty list rejects all requests.
Domain matching rules:
* Enter hostnames only: `www.example.com`, not `https://www.example.com` or `www.example.com:443`.
* Each hostname must match exactly. `example.com` does not cover `www.example.com`. Add both if you serve both.
* Matching is case-insensitive and ignores ports.
* For local testing, add `localhost`.
The Chat Widget HTML section on the Chatbot settings page shows a ready-to-copy `
```
The `async` attribute keeps it off your critical render path. The script URL is stable and never changes.
Open your site in a browser. A bubble should appear in the corner of the page. Click it, send a test question, and confirm the agent streams back an answer.
If the bubble is missing or messages fail, see [troubleshooting](/it/chat-widget/troubleshooting).
## Full page example
```html theme={null}
My Company
Welcome to My Company
Click the chat button to ask a question.
```
## Framework installs
The widget is framework-agnostic. Any approach that puts the script tag in the rendered page works.
```html Plain HTML theme={null}
```
```tsx React theme={null}
// Load once at the app root.
import { useEffect } from 'react';
export function CircuitChatWidget() {
useEffect(() => {
if (document.querySelector('script[src*="chat-embed.circuit.ai"]')) return;
const script = document.createElement('script');
script.src =
'https://chat-embed.circuit.ai/launcher.js?apiKey=YOUR_AGENT_KEY';
script.async = true;
document.body.appendChild(script);
}, []);
return null;
}
```
```tsx Next.js theme={null}
// app/layout.tsx (App Router)
import Script from 'next/script';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
In single-page apps, load the script once at the application root rather than inside a routed page component. The widget persists across client-side navigation. Re-injecting the script tag has no effect because the launcher is idempotent.
## CMS and tag manager installs
Create a new tag of type Custom HTML, paste the script tag, and set the trigger to All Pages. GTM injects the script on page load.
Add the script tag to your theme's footer using your theme's custom code setting (often under Appearance) or a header/footer code plugin. Avoid pasting it into individual posts.
In your admin, go to Online Store, then Themes, then Edit code. Open `theme.liquid` and paste the script tag immediately before the closing ` ` tag. Add your `.myshopify.com` hostname to the allowed domains list if you need the widget to work in theme preview.