Skip to main content
The web widget puts your assistant on your website: visitors click a button and talk to the assistant in the browser (no phone or app required) or type in a chat with the same assistant. The widget is available when included in your plan.

​
Voice + chat, one assistant

  • Voice — a click starts a live voice conversation using the assistant’s full configuration: engine mode, voice, knowledge base, tools, guardrails. Web calls appear in History with direction web.
  • Chat — the same assistant, prompts, and knowledge base in text form, for visitors who can’t or won’t speak.
Because both channels share one assistant configuration, you maintain behavior in one place.

​
Embedding

Create a widget under Settings → Channels → Web Widget, then paste a snippet from the editor. Choose Display:
The default — a corner launcher bubble. Position and Initial state apply. Prefer the script loader (it sets allow="microphone" on the iframe automatically):
See the embed panel for ready-made HTML, React, and Markdown snippets. On white-label domains the widget is served from your tenant domain with your branding.

​
Allowed origins

List the website(s) that may embed the widget (exact origins like https://example.com, or subdomain wildcards like *.example.com). Localhost is supported for development. Origins are optional when creating or saving a widget.
  • An empty allowlist does not mean “open to any site”: foreign origins are blocked. Only the platform domain itself stays allowed so the in-app live preview keeps working.
  • Add every website host that will load the snippet before going live. If the widget fails to load on a customer site, check Allowed origins first.

​
Customization

  • Display — Floating (corner launcher) or Inline (in-page embed). Position and Initial state only apply to Floating.
  • Colors and branding — launcher color, panel accent, logo; tenant branding applies automatically on white-label domains.
  • Position — corner placement of the floating launcher (hidden for Inline).
  • Modes — voice-only, chat-only, or both.
  • Voice presence — classic audio visualizer, or a virtual AI avatar (see below).
  • Launcher icon — Milian, Chat bubbles, Question mark, Smiley face, Team, or Hand wave. Applies to chat-only, voice-only, and both.
  • Launcher label — presets (No text default; Help, Ask anything, Assistance, Support, Live Chat, Need help?) translated from the visitor’s browser language. Avatar-only still uses optional custom launcher text for the glass CTA.
  • Texts — welcome message, AI disclosure, privacy notice.
  • Pre-chat form — optional form before chat or voice starts (see below).

​
Virtual AI avatar

Virtual avatars require the AI Avatar feature. In the widget editor, set Voice presence to AI avatar and pick an avatar.
  • Layouts
    • Avatar only (full-bleed) — compact card focused on the face. Floating widgets can start Expanded or Minimized; Inline always shows the card in place.
    • Avatar + chat — avatar presence with the classic chat/voice panel chrome.
  • Billing — voice sessions bill the normal talk-minute rate, plus the Web widget virtual avatar surcharge per minute while a virtual avatar is active; plain text chat messages sent and received bill credits per message at the workspace’s Web chat (sent) / Web chat (received) rate. Current rates are on the Usage page; see also How usage is billed.
  • Without AI Avatar access, the editor shows an upgrade option and the API rejects enabling avatar presence.

​
Pre-chat form

Open the widget in the editor, find Pre-chat form, and turn on Enable. Visitors then fill in fields before the session starts.
  • Suggestions come from contact fields (name, email, phone), the selected assistant’s input variables, and workspace Audience attributes. You can also add custom keys.
  • Submitted values become call input variables ({{variable_key}}), update the Audience lead when identity fields are present, and appear in History under Pre-chat form / Input variables.
  • Required fields are validated before a visitor can start a session.

​
Things to check before going live

1

Add at least one allowed origin

List every site that will embed the widget. Without origins, third-party hosts cannot load config or mint tokens.
2

Test the assistant with browser calls first

The widget uses the same web-call path as the assistant editor’s test call — if that sounds right, the widget will too.
3

Mind microphone permissions

Browsers require HTTPS for microphone access. The host page must not block microphone via Permissions-Policy. Script/web-component embeds set allow="microphone" on the iframe automatically.
4

Update your privacy policy

Voice conversations are processed like calls (transcripts, optional recording with consent flow). Mention the widget in your privacy policy.

​
Troubleshooting

Confirm the embed snippet sits before the closing </body> tag, hard-refresh (or test in a private window) to rule out cached HTML, check your plan includes the web widget, and look for JavaScript errors in the browser console. Copy the snippet fresh from the widget editor if you’ve since changed the connector’s key.
Check Allowed origins first. An empty allowlist blocks every foreign host by design; add the exact origin (or a *.example.com wildcard) the widget is embedded on.
Voice requires HTTPS. Confirm the page is served over HTTPS, the browser has granted microphone permission, the microphone works in other apps, and no VPN or firewall is blocking WebRTC. Script and web-component embeds set allow="microphone" automatically — a raw iframe embed needs that attribute added manually.
Check the browser console for errors, confirm the assistant works from a test call/chat in the assistant editor, and reload the page to start a fresh widget session.
Answers arrive under each field’s key, so pick the suggestion (or set the custom key) that matches the variable your assistant reads, and save the widget before testing again.
Make sure you saved the widget settings, then hard-refresh or test in a private window; an old cached embed snippet can also mask a fresh config change.
Use a Custom HTML block, keep the snippet before the closing </body> tag, and clear any caching plugin’s cache after saving. Security/firewall plugins occasionally block the widget script — disable one at a time to isolate the cause.
Still stuck? Test in an incognito window and a second browser to rule out extensions and cached state, then contact support with a screenshot and the browser console output.

​
API & MCP

Manage widgets programmatically via the public REST API (/api/v1/widget-connectors) and MCP tools (create_widget_connector, update_widget_connector, …). allowed_origins is optional; empty or omitted blocks third-party hosts. Scope: assistants:write. Widget and AI Avatar access follow your plan. New widgets initially reuse the selected assistant’s portrait as the header logo when available. You can replace or remove it later.