Skip to main content
Standaard is aan elk telefoonnummer en elke publiceerbare sleutel een statische spraakagent toegewezen. Wanneer je aanpassingen per beller of per bezoeker nodig hebt — VIP-routering, context van ingelogde gebruikers, A/B-tests voor prompts — schakel dan over naar webhookmodus en laat je server beslissen.

Hoe het werkt

  1. Je abonneert je op de gebeurtenis telephony.incoming (telefoon) of web.incoming (widget). Beide zijn blokkerende webhooks: ThunderPhone wacht maximaal 10 seconden op je reactie voordat de oproep wordt voortgezet.
  2. ThunderPhone stuurt je {call_id, from_number, to_number} (widgetsessies bevatten widgetspecifieke velden in plaats van nummers — zie het aanvraagschema).
  3. Je server reageert met een agentconfiguratie (prompt, stem, product, tools). ThunderPhone gebruikt die configuratie voor de oproep.
  4. 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

Abonneer je eindpunt voor telefoonnummers op telephony.incoming:
De reactie bevat een eenmalige 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 op new 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.