Skip to main content
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

One-line install

A single async script tag per widget. Appearance and behavior changes publish from Settings without touching the snippet again.

Unified inbox

Widget conversations appear in /inbox alongside WhatsApp, in real time, with channel-aware affordances (no templates or service-window rules apply to widget chats).

Your AI, not theirs

Per-widget AI mode connects the GBCA agent: draft replies for operator review, or full auto-send until a human takes over.

Origin allowlist

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, 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: 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 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