> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Website Widget
> First-party live-chat widget for your website — visitor conversations land in the Switchbord inbox, with optional GBCA AI replies in draft or auto-send mode.
The website widget puts a Switchbord-native chat bubble on any website you control. Visitor messages arrive in the same operator inbox as WhatsApp conversations, operators reply from the same composer, and — unlike hosted chat vendors that lock you into their own chatbot — the widget can pipe conversations straight into your connected GBCA agent.
If you currently use tawk.to or a similar hosted widget purely for live chat, this is the drop-in replacement path: one script tag, your own AI, your own data.
## What you get
A single async script tag per widget. Appearance and behavior changes publish from Settings without touching the snippet again.
Widget conversations appear in `/inbox` alongside WhatsApp, in real time, with channel-aware affordances (no templates or service-window rules apply to widget chats).
Per-widget AI mode connects the GBCA agent: draft replies for operator review, or full auto-send until a human takes over.
Each widget only serves the domains you list. Requests from anywhere else fail closed.
## Creating a widget
Go to **Settings → Integrations → Channels → Website widget**:
1. Click **Create widget** and give it a display name.
2. Choose a **slug** — this becomes part of the public script URL and the direct chat link, so pick something you're happy to expose (lowercase letters, numbers, hyphens).
3. Add your **allowed origins** — the exact origins (scheme + host, e.g. `https://www.example.com`) of every site that will embed the widget. Subdomains are separate origins.
4. Pick a theme accent color and launcher position, set the widget title and welcome message.
5. Copy the **install snippet** from the Install section and hand it to whoever maintains the website — or use the [install guide](/guides/website-widget-install), which includes framework-specific instructions and a ready-made prompt for AI coding agents.
The **Install diagnostics** card on the same page runs passive checks — public endpoint enabled, origins configured, slug valid — so you can confirm the configuration before the snippet ever ships.
Every widget also gets a hosted **direct chat link** (`/chat/{slug}` on your API domain). Useful for email signatures, QR codes, or testing the widget without touching a website.
## AI agent (GBCA) mode
Each widget has its own AI mode, independent of your WhatsApp auto-reply settings:
| Mode | Behavior |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Off** (default) | Operators handle every message. No AI involvement. |
| **Draft** | Every visitor message generates a GBCA draft in the inbox composer for operator review — same amber-state flow as WhatsApp proactive drafts. |
| **Auto-send** | The GBCA agent replies to visitors automatically. The instant a human operator sends a reply in the conversation, autonomous sends stop and the agent goes back to drafting. |
Auto-send authority is re-checked against the widget's settings at send time, so flipping the mode back to Draft or Off takes effect immediately — including for replies already queued. The workspace-level GB-Agent master switch must be enabled for either AI mode to do anything.
Widget conversations never touch the WhatsApp/Meta dispatch pipeline. AI replies are delivered to the visitor through the widget itself.
## Visitor identity
Out of the box, visitors are anonymous — the widget creates a session and a synthetic contact automatically. Two upgrades are available:
* **Unverified attributes**: your page's JavaScript can call `SwitchbordWidget.setVisitor({...})` to attach a name or email the visitor typed somewhere. These are stored as unverified and can never overwrite verified data.
* **Signed identity (Secure Mode)**: if your site has logged-in users, your backend can mint a short-lived HS256 token so Switchbord knows *verifiably* who the visitor is. Verified visitors resume their previous conversation across sessions and devices. See the [install guide](/guides/website-widget-install#signed-identity-secure-mode) for server-side examples.
You can also set **Require identity** on a widget, which blocks message send/history until the session's visitor has been verified — the widget still boots anonymously so it can perform the login handshake.
When a verified identity matches an existing contact (by email or phone), Switchbord creates a non-destructive **merge suggestion** instead of merging automatically.
## What operators see
* Widget conversations carry the website channel badge; WhatsApp-only affordances (templates, service-window countdown, media upload) are hidden.
* Replies show up to the visitor with the operator's author label; AI replies show the agent's label.
* Visitors see an unread badge on the launcher when replies arrive while the chat is closed.
## Limits and behavior
* Public widget endpoints are rate-limited per workspace (120 requests/minute) on top of platform-level protection.
* AI runs triggered by widget messages are debounced — rapid-fire visitor messages coalesce into a single agent run for the latest message.
* Transcript history is session-scoped: anonymous visitors who clear their browser storage start a fresh conversation. Signed identity is the durable cross-device thread.
## Next steps
* [Install the widget on your website](/guides/website-widget-install) — snippet, frameworks, SDK reference, signed identity, and an AI-agent install prompt.
* [GB-Agent connector](/platform/gb-agent-connector) — how the GBCA agent itself is wired to your workspace.