Developer cookbook

Web-Widget einbetten

Fügen Sie Ihrer Marketing- oder Support-Website mit einem einzigen Script-Tag einen Sprachagenten hinzu – Besucher sprechen direkt im Browser mit ihm, ganz ohne Telefonnummer.

Das Web-Widget ermöglicht Ihren Website-Besuchern über das Mikrofon des Browsers ein Gespräch per Klick mit einem Sprachagenten. Es ist ein separates JavaScript-/React-SDK mit einer eigenen SDK-Referenz — dieser Leitfaden konzentriert sich auf die ThunderPhone-seitige Einrichtung, die das Widget benötigt.

Voraussetzungen#

1. Erstellen Sie einen Agenten

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

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

   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.

Erstellen Sie einen veröffentlichbaren Schlüssel#

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"]
  }'

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"]
  }'

Die Antwort enthält einen key, der mit pk_live_... beginnt. 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.

Fügen Sie das Widget auf Ihrer Website ein#

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

Alle drei akzeptieren denselben publishableKey und rendern die Mikrofontaste sowie das Audioelement für Anrufe.

Der context des Widgets wird auf 12.000 Zeichen gekürzt (etwa 3.400 Tokens typischen englischen Texts) und zählt zum Zuschlag 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-Nutzlast auf. Geben Sie die Agentenkonfiguration zurück, die für diesen Besucher ausgeführt werden soll — sie folgt demselben Antwortschema wie Telefonanrufe:

{
  "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 einfließen lassen und Agenten je nach Rollout wechseln.

Sitzungen überwachen#

Widget-Sitzungen erscheinen in GET /v1/calls mit direction="widget" — 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#