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

# Web-Widget einbetten

> Fügen Sie einen Sprachagenten zu Ihrer Marketing- oder Support-Website hinzu – keine Telefonnummer erforderlich.

Das Web-Widget ermöglicht Ihren Websitebesuchern über das Mikrofon des Browsers eine Klick-zum-Sprechen-Unterhaltung mit einem KI-Agenten. Es ist ein separates JavaScript-/React-SDK mit eigener [SDK-Referenz](/de/widget/overview) — dieser Leitfaden konzentriert sich auf die ThunderPhone-seitige Einrichtung, die das Widget benötigt.

<Note>
  Sie können all dies ohne cURL erledigen: Die Dashboard-Seite **Web-Widgets**
  (`/dashboard/web-widgets`) erstellt das Widget, legt seinen Modus und Agenten
  fest, verwaltet zulässige Domains und stellt Ihnen das Einbettungs-Snippet bereit.
</Note>

## Voraussetzungen

<Steps>
  <Step title="Agenten erstellen">
    Der Agent, dessen Prompt und Stimme die Widget-Sitzung ausführen. Setzen Sie
    `widget_enabled: true` (der Standardwert).
  </Step>

  <Step title="Routing-Modus festlegen">
    * `mode="agent"` — ein statischer Agent pro Schlüssel. Am einfachsten.
    * `mode="webhook"` — Ihr Server wählt über einen
      [`web.incoming`-Webhook](/de/webhooks/call-incoming) für jeden Besucher den Agenten aus.
      Verwenden Sie dies für angemeldete Benutzer, A/B-Tests oder Routing pro Seite.
  </Step>

  <Step title="Zulässige Domains auflisten">
    Veröffentlichbare Schlüssel sind an Origins gebunden. Sie müssen jeden Hostnamen
    angeben, der das Widget einbettet. `localhost` / `127.0.0.1` sind während der
    lokalen Entwicklung immer zulässig.
  </Step>
</Steps>

## Veröffentlichbaren Schlüssel erstellen

<CodeGroup>
  ```bash Static agent theme={null}
  curl -X POST https://api.thunderphone.com/v1/publishable-key \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name":            "Marketing site (prod)",
      "mode":            "agent",
      "agent_id":        12,
      "allowed_domains": ["example.com", "*.example.com"]
    }'
  ```

  ```bash Dynamic via webhook theme={null}
  curl -X POST https://api.thunderphone.com/v1/publishable-key \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name":            "Support (dynamic)",
      "mode":            "webhook",
      "webhook_url":     "https://example.com/thunderphone/widget-hook",
      "allowed_domains": ["support.example.com"]
    }'
  ```
</CodeGroup>

Die Antwort enthält einen mit `pk_live_...` beginnenden `key`. **Veröffentlichbare
Schlüssel sind absichtlich öffentlich** — sie können sicher in Ihrem Frontend-Bundle
bereitgestellt werden. Alle Felder finden Sie in der [Referenz für veröffentlichbare Schlüssel](/api-reference/publishable-keys).

<Warning>
  `allowed_domains` muss mindestens einen Eintrag enthalten. `*.example.com`
  entspricht Subdomains (z. B. `api.example.com`), aber **nicht** der
  Domain ohne Subdomain. Platzhalter ohne Domain wie `*` oder `*.*` werden abgelehnt.
</Warning>

## Widget auf Ihrer Website einfügen

Drei Integrationsoptionen werden in der
[Widget-SDK-Dokumentation](/de/widget/overview) behandelt:

<CardGroup cols={3}>
  <Card title="React-Komponente" icon="react" href="/de/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`.
  </Card>

  <Card title="Headless-Hook" icon="circle-nodes" href="/de/widget/headless-hook">
    `useThunderPhone()` für benutzerdefinierte UIs.
  </Card>

  <Card title="CDN-Script-Tag" icon="code" href="/de/widget/cdn-script-tag">
    `ThunderPhone.mount({...})` für Websites ohne Bundler.
  </Card>
</CardGroup>

Alle drei akzeptieren denselben `publishableKey` und rendern die Mikrofontaste
sowie das Audioelement während des Anrufs.

Der Widget-`context` wird bei 12.000 Zeichen abgeschnitten (etwa 3.400 Token
typischen englischen Texts) und zählt zum
[Aufpreis für die Prompt-Größe](/de/guides/billing-and-topups).

## Webhooks im Widget-Modus

Bei `mode="webhook"` ruft ThunderPhone Ihre `webhook_url` bei jedem Sitzungsstart
mit einer `web.incoming`-Payload auf. Geben Sie die Agentenkonfiguration zurück,
die für diesen Besucher ausgeführt werden soll — sie folgt demselben
[Antwortschema](/de/webhooks/call-incoming) wie Telefonanrufe:

```json theme={null}
{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}
```

Sie können Kontext aus Ihrer eigenen Sitzung (welcher Kunde gerade browsed,
auf welcher Seite er sich befindet) in den Prompt einfügen und Agenten je nach
Rollout austauschen.

## Sitzungen überwachen

Widget-Sitzungen werden in
[`GET /v1/calls`](/api-reference/calls#list-calls) mit
`direction="widget"` angezeigt — mit demselben Transkript, derselben Aufzeichnung, Bewertung und
Abrechnung wie Telefonanrufe. Filtern Sie nach `direction`, um ein Dashboard nur für Widgets zu erstellen.

***

## Nächste Schritte

<CardGroup cols={2}>
  <Card title="Widget-SDK-Referenz" icon="window-maximize" href="/de/widget/overview">
    Details zur React-, Hook- und CDN-Integration.
  </Card>

  <Card title="Dynamische Konfiguration pro Anruf" icon="bolt" href="/de/guides/dynamic-call-config">
    Implementieren Sie den Ablauf `mode="webhook"` vollständig.
  </Card>

  <Card title="Referenz für veröffentlichbare Schlüssel" icon="key" href="/api-reference/publishable-keys">
    Jedes Feld der Schlüsselressource.
  </Card>

  <Card title="Mic-Sitzungen-API" icon="microphone" href="/api-reference/mic-sessions">
    Überspringen Sie das Widget; steuern Sie LiveKit direkt für benutzerdefinierte UIs.
  </Card>
</CardGroup>