Skip to main content
Standardmäßig ist jeder Telefonnummer und jedem veröffentlichbaren Schlüssel ein statischer Agent zugewiesen. Wenn Sie pro Anrufer oder pro Besucher Anpassungen benötigen — VIP-Routing, Kontext angemeldeter Benutzer, A/B-Tests für Prompts — wechseln Sie in den Webhook-Modus und lassen Sie Ihren Server entscheiden.

So funktioniert es

  1. Abonnieren Sie das Ereignis telephony.incoming (Telefon) oder web.incoming (Widget). Beide sind blockierende Webhooks: ThunderPhone wartet bis zu 10 Sekunden auf Ihre Antwort, bevor der Anruf fortgesetzt wird.
  2. ThunderPhone sendet Ihnen {call_id, from_number, to_number} (Widget- Sitzungen enthalten statt Nummern widgetspezifische Felder — siehe das Anfrageschema).
  3. Ihr Server antwortet mit einer Agentenkonfiguration (Prompt, Stimme, Produkt, Tools). ThunderPhone verwendet diese Konfiguration für den Anruf.
  4. Wenn Sie {} zurückgeben, ein Timeout auftritt oder ein Fehler entsteht, wird der statisch zugewiesene Agent als Fallback verwendet. Sichere Standardeinstellung.
Funktioniert identisch für Telefonanrufe (telephony.incoming) und Widget- Sitzungen (web.incoming), unabhängig davon, ob sie an einen Webhook-Endpunkt oder an den Legacy-Webhook mit einer einzelnen URL zugestellt werden.

1. Webhook-Ziel konfigurieren

Abonnieren Sie für Telefonnummern telephony.incoming für Ihren Endpunkt:
Die Antwort enthält ein einmaliges secret — speichern Sie es; Sie benötigen es für die Signaturverifizierung.

2. Implementieren Sie den Handler

Drei Faustregeln:
  • Überprüfen Sie die Signatur bei jeder Anfrage (siehe Webhook-Signaturen überprüfen). Überspringen Sie dies nicht in der Entwicklung — machen Sie es einmal richtig und verwenden Sie es erneut.
  • Antworten Sie schnell. Zehn Sekunden sind die harte Obergrenze, und jede Sekunde ist Stille für den Anrufer. Führen Sie bei Bedarf Datenbankabfragen durch, aber rufen Sie nachgelagerte LLMs nicht synchron auf — wenn Sie eine dynamische Prompt-Generierung benötigen, berechnen Sie diese vorab und speichern Sie sie im Cache.
  • Sorgen Sie für einen sauberen Fallback. Jeder unerwartete Zustand sollte {} zurückgeben, damit der statisch zugewiesene Agent den Anruf bearbeitet.

3. Antwortschema

Der Antworttext entspricht exakt dem Antwortschema für eingehende Anrufe. Die häufig verwendeten Felder:
Die Sprechreihenfolge pro Anruf und max_hold_seconds sind in der Webhook-Antwort nicht verfügbar. Legen Sie sie für den referenzierten Agenten fest.

Muster

Kontext angemeldeter Benutzer

In Widgets im Webhook-Modus weiß die Seite des Besuchers bereits, wer er ist. Rufen Sie Ihren Webhook mit einem Query-String-Parameter auf, den das Widget-SDK weiterleitet (?customer_id=123), und suchen Sie den Kunden serverseitig.

A/B-Prompt-Rollout

Bevor Sie dies selbst implementieren, beachten Sie, dass ThunderPhone über eine native Funktion für Experimente verfügt (/dashboard/experiments und den Tab A/B im Agent-Builder), die Varianten definiert, Traffic aufteilt und Ergebnisse pro Variante vergleicht — kein Webhook erforderlich. Wenn Sie dennoch eine Steuerung auf Webhook-Seite benötigen: Hash von call_id → Bucket; stellen Sie Prompt A für 0..49 und Prompt B für 50..99 bereit. Speichern Sie den gewählten Bucket in Ihrer eigenen Datenbank und korrelieren Sie ihn später mit der Bewertung des abgeschlossenen Anrufs.

Zeitbasierte Weiterleitung

Geschäftszeiten → Agent für „Live-Support“; außerhalb der Geschäftszeiten → Agent zum „Aufnehmen einer Nachricht“. Reine Umschaltung auf new Date().getUTCHours() in Ihrem Handler.

Nächste Schritte

Referenz für Webhooks bei eingehenden Anrufen

Exakte Anfrage- und Antwortschemata, einschließlich aller Konfigurationsschlüssel.

Webhook-Signaturen verifizieren

Richten Sie HMAC einmal korrekt ein und verwenden Sie es überall wieder.

Eine Tool-Integration erstellen

Kombinieren Sie dynamische Weiterleitung mit agentenspezifischen Tools.

Zustellungssemantik

Wiederholungen, Reihenfolge, Timeouts.