Skip to main content

​
Web widget

The web widget is an embeddable chat experience you drop onto any page — a floating bubble that opens a panel, or a full-screen page you link to directly.

​
Embed it

Each web-widget channel has a public key. Add this snippet to your page, before the closing </body> tag, with your channel’s key:
The channel’s Install tab has this snippet pre-filled with your key — copy it from there. The loader fetches the channel’s configuration — branding, greeting, identity mode — so you can change those in the console without touching the page.

​
Allow your site’s origin

Every page origin that embeds the widget must be listed in the channel’s Allowed origins. Requests from an unlisted origin are refused — the widget simply won’t load — so this is the first thing to check when an embed shows nothing. Add each origin exactly (https://intranet.example.com), including any staging hosts you test from. The admin console’s own preview origin is handled for you.

​
Choose how users are identified

Set the channel’s identity mode to match where you’re embedding it: If the agent acts on a user’s behalf, use Embedded token or Federated so requests are tied to a real identity — both sign the user in silently when the widget is embedded in an app they’re already logged into. Don’t use interactive hosted sign-in for an embedded widget. For the full picture — trust tiers, and which modes can act as the user vs. only attribute — see End-user identity.

​
Brand it

Configure the widget’s appearance on the channel’s settings — no code:
  • Display name and role shown in the header.
  • Avatar image (falls back to a generated initial).
  • Primary color for the launcher and the user’s message bubbles, with an optional header color and a second color for a subtle gradient.
  • Corner radius for the overall shape.
  • Greeting and up to a handful of suggested prompts shown when the conversation is empty.
  • Preferred voice for read-aloud.
Pick a primary color with enough contrast against white text — the widget uses it behind message text and on the send button.

​
What the conversation includes

The widget is a full conversational surface, not just a text box:
  • Rich answers — markdown, tables, code, images and other media inline, with citations and source cards when the agent draws on indexed content, and live activity indicators while it works.
  • Attachments — users can upload a file or screenshot for the agent to look at.
  • Voice — three distinct things, all optional: dictation (speak instead of type), voice mode (a real-time spoken conversation), and read-aloud (the agent’s answer spoken back, in the channel’s preferred voice).
  • Feedback — thumbs up/down with categories, feeding the agent’s reporting.
  • Forms and confirmations — structured forms for multi-field requests; confirmation prompts before actions; per-user sign-in consent cards when a tool acts as the user in another system.
  • Human handoff — when a conversation is handed to a live agent, the transition and the human’s replies render right in the thread.

​
Anonymous channels and browser storage

Two things to know before a public, no-sign-in embed:
  • Rate limits. Anonymous visitors get per-visitor limits on uploads, dictation, and voice, plus a per-tenant daily cap on anonymous voice minutes — so an abusive visitor can’t run up your usage.
  • Browser storage. An anonymous visitor is remembered with browser storage. When your page and the widget are on different sites, some browsers partition or block that storage (third-party cookie rules); the widget falls back to asking for storage access, and if the browser still refuses, the visitor gets a fresh session per visit. Signed-in identity modes (embedded token, federated) don’t have this problem — prefer them wherever users are authenticated.

​
Widget and full-screen share a conversation

The same channel can render as the compact widget or as a full-screen page. A user can move between them and keep the same conversation, history, and unsent draft — useful when a quick question turns into a longer session.

​
On SharePoint Online

Modern SharePoint Online forbids pasting the <script> snippet on a page. To put this widget on a SharePoint intranet — with single sign-on for logged-in Microsoft 365 users — use the dedicated SharePoint package and guide: Deploy to SharePoint Online. You download the package from this channel’s Install tab (Deploy to → SharePoint site).

​
Troubleshooting

Almost always an allowed origins problem: the page’s origin isn’t on the channel’s list, so the config request is refused. Add the exact origin (scheme and host, e.g. https://intranet.example.com) and hard-refresh. The browser console shows the refused request.
On a cross-site anonymous embed, the browser is partitioning or blocking the widget’s storage (third-party cookie rules). Use a signed-in identity mode (embedded token or federated) where visitors are authenticated; for a truly public embed this is expected behavior.
Branding is fetched by the loader at runtime, so changes apply without re-embedding — but a cached page may hold the old config. Hard-refresh. If you changed the channel key, update the snippet.
The embedding page must permit microphone access. On SharePoint, see the SharePoint guide’s troubleshooting.