Skip to main content
Wanneer een inkomend telefoongesprek een nummer bereikt zonder toegewezen spraakagent, of wanneer een webwidgetsessie wordt gestart met een publiceerbare sleutel in mode="webhook", stuurt ThunderPhone een blokkerend telephony.incoming / web.incoming-verzoek naar je verouderde webhook-URL en wacht het maximaal 10 seconden op een configuratieantwoord. Gebruik deze uitwisseling om per gesprek dynamisch een prompt, stem en tools te kiezen — zie de handleiding voor dynamische gespreksconfiguratie voor het volledige patroon.
Geabonneerde webhook-eindpunten ontvangen ook telephony.incoming / web.incoming — voor elk inkomend gesprek en elke websessie, ongeacht of een spraakagent is geconfigureerd — maar die leveringen zijn fire-and-forget-notificaties met een event_id en nooit blokkerend. Alleen de verouderde webhook met één URL bevat de configuratie-uitwisseling op deze pagina. De vormen van eindpuntnotificaties staan in de gebeurteniscatalogus.
De blokkerende uitwisseling heeft geen fallback: als je handler een niet-2xx-status retourneert, een time-out krijgt of een configuratie retourneert die de validatie niet doorstaat, wordt het gesprek geweigerd (het telefoongesprek wordt niet verbonden; het verzoek voor de widgetsessie mislukt met 502/422). Reageer snel — de beller hoort een kiestoon terwijl je beslist.

Request-payload

Voor telefoongesprekken (telephony.incoming):
Voor webwidgetsessies (web.incoming) identificeert data de pagina waarin de widget is ingesloten in plaats van telefoonnummers:
Widgets in webhookmodus leveren dit verzoek af bij de eigen webhook_url van de publiceerbare sleutel wanneer die is ingesteld, met fallback naar de webhook-URL op organisatieniveau. In beide gevallen is het ondertekend met de webhook-secret van de organisatie.

Antwoordschema

Retourneer een JSON-object dat de configuratie van de spraakagent voor deze oproep beschrijft. prompt en voice zijn vereist; al het andere is optioneel.
Onbekende sleutels op het hoogste niveau worden stilzwijgend genegeerd — een veldnaam met een typefout weigert de configuratie niet, maar wordt gewoon niet toegepast. Spreekvolgorde en max_hold_seconds worden hier niet geaccepteerd; ze zijn alleen configureerbaar op de spraakagent zelf.
Omdat prompt en voice vereist zijn, weigert het retourneren van {} of een antwoord dat de validatie niet doorstaat de oproep met 422 — er is geen fallback naar een statische spraakagent op dit pad (een nummer of sleutel in webhookmodus heeft geen toegewezen spraakagent).

Limiet voor antwoordgrootte

Configuratieantwoorden zijn beperkt tot 5 MiB. Als een handler een groter antwoord retourneert, ook met een 2xx-status, meldt ThunderPhone dat het antwoord de limiet heeft overschreden en weigert de oproep- of widgetsessie. Beperk het antwoord tot de velden die nodig zijn voor het instellen van de oproep; host grote gegevens achter functietools of een andere service in plaats van ze in de configuratie in te sluiten.

Voorbeeldhandler


Antwoord met functietools

Koppel tools zodat de AI tijdens het gesprek je API’s kan aanroepen:
Aanvragen naar tool-endpoints worden ondertekend met hetzelfde organisatie-webhookgeheim dat deze uitwisseling heeft ondertekend. Zie Function Tools voor de exacte structuur en de indeling van het ondertekende verzoek.

Spiekbriefje voor productpakketten


Gerelateerd

telephony.complete / web.complete

De niet-blokkerende gebeurtenis aan het einde van een oproep.

Functietools

Volledig JSON-schema voor tools[] en het ondertekende endpointcontract.

Webhook-endpoints

Abonneer meerdere URL’s op telephony.incoming / web.incoming.

Dynamische oproepconfiguratie

Patronen voor prompts, tools en A/B-tests per beller.