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 (WebRTC — no phone, no app) or type in a chat with the same assistant brain. Availability is plan-gated (web_widget).

​
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 your call 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:
  • Floating (default) — corner launcher bubble; Position and Initial state apply. Prefer the script loader (it sets allow="microphone" on the iframe automatically):
  • Inline — widget sits in your page flow (no launcher). Prefer the web component or iframe snippet (portrait sizing included for avatar cards):
Or mount into a target node: data-famulor-target="#famulor-assistant" on the script tag. 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 production (and staging) 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).
  • Texts — launcher label, welcome message, AI disclosure, privacy notice.
  • Pre-chat form — optional form before chat or voice starts (see below).

​
Virtual AI avatar

Plan-gated separately (ai_avatar). 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 (Anam-style). 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 — avatar voice minutes bill the normal talk-minute rate plus an avatar surcharge (currently +80 credits/min). See How minutes are billed and Usage in the app.
  • Without ai_avatar on the plan, the editor shows an upgrade gate and the API rejects enabling avatar presence.

​
Pre-chat form

In Widgets → open a connector → enable Pre-chat form. Visitors fill 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.
  • Config is stored on the widget connector (theme.preform) and exposed in the public widget config; the token endpoint validates required fields.

​
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.

​
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/omitted blocks third-party hosts). Scope: assistants:write. Plan-gate: web_widget (avatar presence also needs ai_avatar).