> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Web widget

> Embed your assistant as a voice and chat widget on any website

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](/monitoring/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**:

<Tabs>
  <Tab title="Floating">
    The default — a corner launcher bubble. Position and Initial state apply. Prefer the **script** loader (it sets `allow="microphone"` on the iframe automatically):

    ```html theme={null}
    <script
      src="https://YOUR-DOMAIN/widget.js"
      data-famulor-key="wgt_YOUR_PUBLIC_KEY"
      async
    ></script>
    ```
  </Tab>

  <Tab title="Inline">
    The widget sits in your page flow (no launcher). Prefer the web component or iframe snippet (portrait sizing included for avatar cards):

    ```html theme={null}
    <famulor-widget
      data-key="wgt_YOUR_PUBLIC_KEY"
      style="display:block;width:100%;max-width:360px;aspect-ratio:9/16;border-radius:20px;overflow:hidden;"
    ></famulor-widget>
    <script src="https://YOUR-DOMAIN/widget.js" async></script>
    ```

    Or mount into a target node: `data-famulor-target="#famulor-assistant"` on the script tag.
  </Tab>
</Tabs>

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](https://app.famulor.io/usage); see also [How usage is billed](/billing/minutes).
* 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Update your privacy policy">
    Voice conversations are processed like calls (transcripts, optional recording with consent flow). Mention the widget in your privacy policy.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget doesn't appear at all">
    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.
  </Accordion>

  <Accordion title="Widget loads elsewhere but not on this site">
    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.
  </Accordion>

  <Accordion title="Voice doesn't start">
    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.
  </Accordion>

  <Accordion title="Chat doesn't respond">
    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.
  </Accordion>

  <Accordion title="Pre-chat form answers don't reach the assistant">
    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.
  </Accordion>

  <Accordion title="Changes in the editor don't show up">
    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.
  </Accordion>

  <Accordion title="Embedding in WordPress or another CMS">
    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.
  </Accordion>
</AccordionGroup>

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.