Skip to main content
Wanneer een inkomend telefoongesprek een nummer zonder toegewezen agent bereikt, of een websidgetsessie start met een publiceerbare sleutel in mode="webhook", stuurt ThunderPhone een blokkerend telephony.incoming / web.incoming-verzoek naar je verouderde webhook-URL en wacht maximaal 10 seconden op een configuratieantwoord. Gebruik deze uitwisseling om per oproep dynamisch een prompt, stem en tools te kiezen — zie de gids voor dynamische oproepconfiguratie voor het volledige patroon.
Geabonneerde webhookendpoints ontvangen ook telephony.incoming / web.incoming — voor elke inkomende oproep en websessie, met of zonder agentconfiguratie — maar deze leveringen zijn fire-and-forget-meldingen met een event_id, nooit blokkerend. Alleen de verouderde webhook met één URL bevat de configuratie-uitwisseling op deze pagina. De structuren van endpointmeldingen staan in de eventcatalogus.
De blokkerende uitwisseling heeft geen fallback: als je handler een niet-2xx-status retourneert, een time-out krijgt of een configuratie retourneert die validatie niet doorstaat, wordt de oproep geweigerd (het telefoongesprek komt niet tot stand; het verzoek voor de widgetsessie mislukt met 502/422). Reageer snel — de beller hoort een overgaattoon terwijl je beslist.

Aanvraagpayload

Voor telefoongesprekken (telephony.incoming):
Voor websidgetsessies (web.incoming) identificeert data de insluitende pagina 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 wordt het ondertekend met de webhook-secret van de organisatie.

Antwoordschema

Retourneer een JSON-object dat de configuratie van de agent voor deze oproep beschrijft. prompt en voice zijn verplicht; al het andere is optioneel.
Onbekende sleutels op hoofdniveau 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 Agent zelf.
Omdat prompt en voice verplicht zijn, weigert het retourneren van {} of een antwoord dat niet door de validatie komt de oproep met 422 — er is geen fallback naar een statische agent via dit pad (een nummer of sleutel in webhookmodus heeft geen toegewezen agent).

Voorbeeldhandler


Antwoord met functietools

Koppel tools zodat de AI tijdens een gesprek je API’s kan aanroepen:
Verzoeken naar tool-endpoints worden ondertekend met hetzelfde webhookgeheim van de organisatie 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-eindpunten

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

Dynamische oproepconfiguratie

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