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

> Bette deinen Assistenten als Sprach- und Chat-Widget in jede Website ein

Das Web-Widget bringt deinen Assistenten auf deine Website: Besucher klicken auf eine Schaltfläche und **sprechen im Browser mit dem Assistenten** (WebRTC – kein Telefon, keine App) oder schreiben im **Chat** mit demselben Assistenten-Gehirn. Die Verfügbarkeit hängt vom Plan ab (`web_widget`).

## Sprache + Chat, ein Assistent

* **Sprache** – ein Klick startet ein Live-Gespräch mit der vollständigen Konfiguration des Assistenten: Engine-Modus, Stimme, Wissensdatenbank, Tools, Guardrails. Web-Anrufe erscheinen in deinem Anrufverlauf mit der Richtung `web`.
* **Chat** – derselbe Assistent, dieselben Prompts und dieselbe Wissensdatenbank in Textform, für Besucher, die nicht sprechen können oder wollen.

Weil sich beide Kanäle eine Assistentenkonfiguration teilen, pflegst du das Verhalten nur an einer Stelle.

## Einbetten

Lege unter **Einstellungen → Kanäle → Web-Widget** ein Widget an und wähle **Anzeige**:

* **Schwebend** (Standard) — Launcher in der Ecke; Position und Ausgangszustand gelten. Empfohlen: Script-Loader (setzt `allow="microphone"` am iframe):

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

* **Inline** — Widget im Seitenfluss (kein Launcher). Empfohlen: Web Component oder iframe:

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

Oder Script mit Ziel-Container: `data-famulor-target="#famulor-assistant"`. Fertige Snippets (HTML, React, Markdown) findest du im Embed-Panel.

## Erlaubte Origins

Trage die Website(s) ein, die das Widget einbetten dürfen (exakte Origins wie `https://example.com` oder Subdomain-Wildcards wie `*.example.com`). Localhost ist für die Entwicklung erlaubt. Origins sind beim Anlegen und Speichern **optional**.

* Eine leere Allowlist bedeutet **nicht** „offen für alle Seiten“: fremde Origins werden blockiert. Nur die Plattform-Domain selbst bleibt erlaubt, damit die Live-Vorschau in der App funktioniert.
* Trage vor dem Livegang jeden Produktions- (und Staging-)Host ein, der das Snippet lädt. Lädt das Widget auf einer Kundenseite nicht, prüfe zuerst Allowed Origins.

## Anpassung

* **Anzeige** – **Schwebend** (Ecken-Launcher) oder **Inline** (Einbettung im Seitenfluss). Position und Ausgangszustand gelten nur für Schwebend.
* **Farben und Branding** – Launcher-Farbe, Panel-Akzent, Logo; das Tenant-Branding greift auf White-Label-Domains automatisch.
* **Position** – Eckplatzierung des schwebenden Launchers (bei Inline ausgeblendet).
* **Modi** – nur Sprache, nur Chat oder beides.
* **Voice Presence** – klassischer Audio-Visualizer oder ein **virtueller AI-Avatar** (siehe unten).
* **Texte** – Launcher-Label, Willkommensnachricht, AI-Hinweis, Datenschutzhinweis.
* **Pre-Chat-Formular** – optionales Formular, bevor Chat oder Sprachgespräch startet (siehe unten).

## Virtueller AI-Avatar

Separat plan-gegated (`ai_avatar`). Im Widget-Editor **Voice Presence** auf **AI avatar** setzen und einen Avatar wählen.

* **Layouts**
  * **Avatar only (full-bleed)** – kompakte Karte mit Fokus auf das Gesicht (Anam-Stil). Schwebend: **Erweitert** oder **Minimiert**; Inline zeigt die Karte direkt im Layout.
  * **Avatar + chat** – Avatar-Präsenz mit klassischem Chat-/Sprach-Panel.
* **Abrechnung** – Avatar-Sprachminuten kosten den normalen Talk-Minute-Tarif **plus einen Avatar-Zuschlag** (aktuell **+80 Credits/min**). Siehe [So werden Minuten abgerechnet](/billing/minutes) und Usage in der App.
* Ohne `ai_avatar` im Plan zeigt der Editor ein Upgrade-Gate; die API lehnt das Aktivieren der Avatar-Präsenz ab.

## Pre-Chat-Formular

Öffne unter **Widgets →** einen Connector → aktiviere **Pre-Chat-Formular**. Besucher füllen Felder aus, bevor die Sitzung beginnt.

* **Vorschläge** stammen aus Kontaktfeldern (Name, E-Mail, Telefon), den Eingabevariablen des gewählten Assistenten und den Audience-Attributen des Workspace. Du kannst auch eigene Keys hinzufügen.
* Übermittelte Werte werden zu **Eingabevariablen** (`{{variable_key}}`) des Anrufs, aktualisieren den Audience-Lead, wenn Identitätsfelder vorhanden sind, und erscheinen im **Verlauf** unter Pre-Chat-Formular / Eingabevariablen.
* Die Konfiguration wird am Widget-Connector (`theme.preform`) gespeichert und in der öffentlichen Widget-Config bereitgestellt; der Token-Endpoint validiert Pflichtfelder.

## Das solltest du vor dem Livegang prüfen

<Steps>
  <Step title="Mindestens eine erlaubte Origin eintragen">
    Liste jede Website, die das Widget einbettet. Ohne Origins können Fremd-Hosts weder Config laden noch Tokens ausstellen.
  </Step>

  <Step title="Teste den Assistenten zuerst mit Browser-Anrufen">
    Das Widget nutzt denselben Web-Call-Pfad wie der Testanruf im Assistenten-Editor – klingt der richtig, passt auch das Widget.
  </Step>

  <Step title="Denk an Mikrofonberechtigungen">
    Browser verlangen HTTPS für den Mikrofonzugriff. Die Host-Seite darf Mikrofon nicht per `Permissions-Policy` blockieren. Script-/Web-Component-Embeds setzen `allow="microphone"` am iframe automatisch.
  </Step>

  <Step title="Aktualisiere deine Datenschutzerklärung">
    Sprachgespräche werden wie Anrufe verarbeitet (Transkripte, optionale Aufzeichnung mit Consent-Flow). Erwähne das Widget in deiner Datenschutzerklärung.
  </Step>
</Steps>

## API & MCP

Widgets lassen sich per öffentlicher REST-API (`/api/v1/widget-connectors`) und MCP-Tools (`create_widget_connector`, `update_widget_connector`, …) verwalten. `allowed_origins` ist optional (leer/weggelassen blockiert Fremd-Hosts). Scope: `assistants:write`. Plan-Gate: `web_widget` (Avatar-Präsenz zusätzlich `ai_avatar`).