Hoe het werkt
- Je abonneert je op de gebeurtenis
telephony.incoming(telefoon) ofweb.incoming(widget). Beide zijn blokkerende webhooks: ThunderPhone wacht maximaal 10 seconden op je reactie voordat de oproep wordt voortgezet. - ThunderPhone stuurt je
{call_id, from_number, to_number}(widgetsessies bevatten widgetspecifieke velden in plaats van nummers — zie het aanvraagschema). - Je server reageert met een agentconfiguratie (prompt, stem, product, tools). ThunderPhone gebruikt die configuratie voor de oproep.
- Als je
{}retourneert, een time-out optreedt of er een fout optreedt, wordt de statisch toegewezen spraakagent als fallback gebruikt. Veilige standaardinstelling.
Werkt identiek voor telefoongesprekken (
telephony.incoming) en widgetsessies
(web.incoming), ongeacht of ze worden afgeleverd bij een webhookeindpunt
of bij de verouderde webhook met één URL.1. Het webhookdoel configureren
- Telefoongesprekken
- Webwidget
Abonneer je eindpunt voor telefoonnummers op De reactie bevat een eenmalige
telephony.incoming:secret — sla deze op; je gebruikt hem
voor handtekeningverificatie.2. Implementeer de handler
Drie vuistregels:- Verifieer de handtekening bij elk verzoek (zie Webhookhandtekeningen verifiëren). Sla dit niet over tijdens ontwikkeling — doe het één keer goed en hergebruik het.
- Reageer snel. Tien seconden is de harde limiet, en elke seconde is stilte voor de beller. Voer indien nodig databasezoekopdrachten uit, maar roep downstream-LLM’s niet synchroon aan — als je dynamische promptgeneratie wilt, bereken deze dan vooraf en cache hem.
- Val netjes terug. Elke onverwachte status moet
{}retourneren, zodat de statisch toegewezen agent het gesprek afhandelt.
3. Antwoordschema
De response body komt exact overeen met het antwoordschema voor inkomende oproepen. De veelgebruikte velden:De spreekvolgorde per gesprek en
max_hold_seconds zijn niet beschikbaar in
de webhookresponse. Stel deze in op de
Agent waarnaar je verwijst.Patronen
Context van ingelogde gebruiker
In widgets in webhookmodus weet de pagina van de bezoeker al wie deze is. Roep je webhook aan met een querystringparameter die de widget-SDK doorstuurt (?customer_id=123) en zoek de klant op aan de serverzijde.
A/B-uitrol van prompts
Voordat je dit zelf implementeert, merk op dat ThunderPhone een ingebouwde functie voor Experimenten heeft (/dashboard/experiments en het tabblad A/B in de agentbuilder) die
varianten definieert, verkeer verdeelt en resultaten per variant vergelijkt —
geen webhook vereist.
Als je toch controle aan de webhookzijde nodig hebt: hash call_id → bucket;
serveer prompt A voor 0..49 en prompt B voor 50..99. Leg vast welke
bucket je hebt gekozen in je eigen database en correleer die later met de
beoordeling van het voltooide gesprek.
Tijdgebaseerde routering
Openingstijden → agent voor “live support”; buiten openingstijden → agent voor “een bericht opnemen”. Een eenvoudige switch opnew Date().getUTCHours() in je handler.
Volgende stappen
Webhookreferentie voor inkomende oproepen
Exacte aanvraag- en antwoordschema’s, inclusief elke configuratiesleutel.
Webhookhandtekeningen verifiëren
Stel de HMAC één keer correct in; hergebruik deze overal.
Een toolintegratie bouwen
Combineer dynamische routering met tools per agent.
Leveringssemantiek
Nieuwe pogingen, volgorde, time-outs.