> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ouraicalling.com/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** (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):

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

* **Inline** — 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.

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](/billing/minutes) 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

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

## 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`).