So funktioniert es
- Abonnieren Sie das Ereignis
telephony.incoming(Telefon) oderweb.incoming(Widget). Beide sind blockierende Webhooks: ThunderPhone wartet bis zu 10 Sekunden auf Ihre Antwort, bevor der Anruf fortgesetzt wird. - ThunderPhone sendet Ihnen
{call_id, from_number, to_number}(Widget- Sitzungen enthalten statt Nummern widgetspezifische Felder — siehe das Anfrageschema). - Ihr Server antwortet mit einer Agentenkonfiguration (Prompt, Stimme, Produkt, Tools). ThunderPhone verwendet diese Konfiguration für den Anruf.
- 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
- Telefonanrufe
- Web-Widget
Abonnieren Sie für Telefonnummern Die Antwort enthält ein einmaliges
telephony.incoming für Ihren Endpunkt: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 aufnew 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.