Skip to main content
Wenn ein eingehender Telefonanruf eine Nummer ohne zugewiesenen Agenten erreicht oder eine Web-Widget-Sitzung mit einem veröffentlichbaren Schlüssel im mode="webhook" startet, sendet ThunderPhone eine blockierende telephony.incoming- / web.incoming-Anfrage an Ihre Legacy-Webhook-URL und wartet bis zu 10 Sekunden auf eine Konfigurationsantwort. Nutzen Sie diesen Austausch, um Prompt, Stimme und Werkzeuge pro Anruf dynamisch auszuwählen — das vollständige Muster finden Sie im Leitfaden zur dynamischen Anrufkonfiguration.
Abonnierte Webhook-Endpunkte erhalten ebenfalls telephony.incoming / web.incoming — für jeden eingehenden Anruf und jede Web-Sitzung, unabhängig davon, ob ein Agent konfiguriert ist — diese Zustellungen sind jedoch Fire-and-forget-Benachrichtigungen mit einer event_id und niemals blockierend. Nur der Legacy-Webhook mit einzelner URL überträgt den Konfigurationsaustausch auf dieser Seite. Die Strukturen der Endpunktbenachrichtigungen finden Sie im Ereigniskatalog.
Der blockierende Austausch hat keinen Fallback: Wenn Ihr Handler einen Nicht-2xx-Status zurückgibt, ein Timeout auftritt oder eine Konfiguration zurückgibt, die die Validierung nicht besteht, wird der Anruf abgelehnt (der Telefonanruf wird nicht verbunden; die Anfrage der Widget-Sitzung schlägt mit 502/422 fehl). Antworten Sie schnell — der Anrufer hört ein Freizeichen, während Sie entscheiden.

Anfrage-Payload

Für Telefonanrufe (telephony.incoming):
Bei Web-Widget-Sitzungen (web.incoming) identifiziert data die einbettende Seite anstelle von Telefonnummern:
Widgets im Webhook-Modus senden diese Anfrage an die eigene webhook_url des veröffentlichbaren Schlüssels, wenn eine festgelegt ist, und greifen andernfalls auf die Webhook-URL auf Organisationsebene zurück. In beiden Fällen wird sie mit dem Webhook-secret der Organisation signiert.

Antwortschema

Geben Sie ein JSON-Objekt zurück, das die Agentenkonfiguration für diesen Anruf beschreibt. prompt und voice sind erforderlich; alles andere ist optional.
Unbekannte Schlüssel der obersten Ebene werden stillschweigend ignoriert — ein Feldname mit Tippfehler lehnt die Konfiguration nicht ab, wird jedoch nicht angewendet. Reihenfolge beim Sprechen und max_hold_seconds werden hier nicht akzeptiert; sie können nur für den Agenten selbst konfiguriert werden.
Da prompt und voice erforderlich sind, lehnt die Rückgabe von {} oder jede Antwort, die die Validierung nicht besteht, den Anruf mit 422 ab — auf diesem Pfad gibt es keinen Fallback auf einen statischen Agenten (eine Nummer oder ein Schlüssel im Webhook-Modus hat keinen zugewiesenen Agenten).

Beispiel-Handler


Antwort mit Funktionstools

Fügen Sie Tools hinzu, damit die KI Ihre APIs während eines Gesprächs aufrufen kann:
Anfragen an Tool-Endpunkte werden mit demselben Webhook-Secret der Organisation signiert, das auch diesen Austausch signiert hat. Die genaue Struktur und das Format der signierten Anfrage finden Sie unter Function Tools.

Produktstufen-Übersicht


Verwandte Inhalte

telephony.complete / web.complete

Das nicht blockierende Ereignis am Ende des Anrufs.

Function Tools

Vollständiges JSON-Schema für tools[] und den Vertrag für signierte Endpunkte.

Webhook-Endpunkte

Abonnieren Sie mehrere URLs für telephony.incoming / web.incoming.

Dynamische Anrufkonfiguration

Muster für anruferspezifische Prompts, Tools und A/B-Tests.