Skip to main content
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 — dieser Leitfaden konzentriert sich auf die ThunderPhone-seitige Einrichtung, die das Widget benötigt.
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.

​
Voraussetzungen

1

Agenten erstellen

Der Agent, dessen Prompt und Stimme die Widget-Sitzung ausführen. Setzen Sie widget_enabled: true (der Standardwert).
2

Routing-Modus festlegen

  • mode="agent" — ein statischer Agent pro Schlüssel. Am einfachsten.
  • mode="webhook" — Ihr Server wählt über einen web.incoming-Webhook für jeden Besucher den Agenten aus. Verwenden Sie dies für angemeldete Benutzer, A/B-Tests oder Routing pro Seite.
3

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.

​
Veröffentlichbaren Schlüssel erstellen

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

​
Widget auf Ihrer Website einfügen

Drei Integrationsoptionen werden in der Widget-SDK-Dokumentation behandelt:

React-Komponente

<ThunderPhoneWidget publishableKey="pk_live_..." />.

Headless-Hook

useThunderPhone() für benutzerdefinierte UIs.

CDN-Script-Tag

ThunderPhone.mount({...}) für Websites ohne Bundler.
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.

​
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 wie Telefonanrufe:
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 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

Widget-SDK-Referenz

Details zur React-, Hook- und CDN-Integration.

Dynamische Konfiguration pro Anruf

Implementieren Sie den Ablauf mode="webhook" vollständig.

Referenz für veröffentlichbare Schlüssel

Jedes Feld der Schlüsselressource.

Mic-Sitzungen-API

Überspringen Sie das Widget; steuern Sie LiveKit direkt für benutzerdefinierte UIs.