Webhook tijdens het gesprek

Met een webhook tijdens het gesprek geef je de assistent een "tool" in handen: op het moment dat de beller iets vraagt wat in je systeem staat, roept de assistent je endpoint aan en verwerkt het antwoord in het gesprek. Dit artikel beschrijft hoe je zo'n tool instelt en wat er over de lijn gaat.

Wanneer wordt hij aangeroepen?

De assistent beslist zelf, op basis van wat je invult bij Wanneer moet de assistent dit gebruiken?, of de tool nodig is. Bijvoorbeeld: "Als de beller vraagt naar de status van een bestelling en een ordernummer noemt." De assistent verzamelt eerst de parameters die je verplicht hebt gemaakt (en vraagt ernaar als de beller ze nog niet heeft genoemd) en doet dan het verzoek. Zodra het antwoord binnen is, gaat het gesprek verder.

Eén gesprek kan de tool meerdere keren aanroepen, bijvoorbeeld als de beller twee ordernummers noemt. De tool werkt op elk kanaal, dus ook in sms, WhatsApp en webchat.

Instellen

Hiervoor heb je de rol Bewerker of Beheerder nodig.

1. Open de assistent onder Assistenten, ga naar het tabblad Taken en klap de kaart Acties open. Klik op Nieuw toevoegen en kies HTTP-verzoek.
2. Geef de actie bij Naam een duidelijke naam (bijvoorbeeld "Orderstatus opzoeken") en kies bij Wanneer voor Tijdens het gesprek.
3. Kies de Methode en vul de URL van je endpoint in. Heeft je systeem dat nodig, vul dan ook Headers of een Authorization-sleutel in.
4. Laat het Body-sjabloon leeg om het standaardverzoek van hieronder te sturen, of bouw een eigen body met {{orderNumber}}.
5. Voeg bij Parameters die de assistent invult met Variabele toevoegen je parameters toe: per parameter een naam, een type en een beschrijving waarmee het AI-model weet wat het moet invullen.
6. Vul een Toelichting op het antwoord in.
7. Vul onderaan Wanneer moet de assistent dit gebruiken? in.

Wijzigingen worden automatisch opgeslagen zodra de actie een naam en een geldig webadres heeft. In Uitproberen wordt het verzoek alleen echt verstuurd als Acties echt uitvoeren aanstaat. Anders krijgt de assistent een gesimuleerd antwoord.

Instelling	Betekenis	Standaard
Wanneer moet de assistent dit gebruiken?	Wanneer de assistent de tool gebruikt. Schrijf het als een zin voor het AI-model.	Leeg: de assistent gaat dan alleen af op de naam van de actie
Parameters die de assistent invult	De gegevens die de assistent uit het gesprek haalt en meestuurt. Per parameter: naam (letters, cijfers en underscores, en het eerste teken is een letter), type (string, number, boolean), beschrijving en of hij verplicht is.	Geen
Toelichting op het antwoord	Uitleg voor het AI-model over wat je antwoord bevat en hoe het dat moet gebruiken, bijvoorbeeld "Noem de status en de verwachte leverdatum in gewone taal. Noem geen interne veldnamen."	Leeg

Aan de telefoon kan de assistent in een paar woorden zeggen dat hij het nakijkt terwijl het verzoek loopt.

Voorbeeld van een parameter:

Naam	Type	Beschrijving
orderNumber	string	Het ordernummer dat de beller noemt, bijvoorbeeld A-2231. Altijd een letter, een streepje en vier cijfers.

Een goede beschrijving voorkomt dat de assistent een postcode of telefoonnummer als ordernummer aanziet.

Het verzoek

Standaard sturen wij een POST met JSON. Elk verzoek met een body krijgt de header X-Yarla-Signature (zie Webhooks). Een GET-verzoek heeft geen body en wordt niet ondertekend. Zet de parameters dan in de URL, bijvoorbeeld https://api.voorbeeld.nl/orders/{{orderNumber}}.

Met een leeg Body-sjabloon staan de parameters als losse velden in een JSON-object:

{ "orderNumber": "A-2231" }

Daarnaast kunnen gegevens meekomen die al bij het gesprek horen, als velden op hetzelfde niveau: bijvoorbeeld de variabelen van een campagne of een API-gesprek, de naam bij een gesprek dat je vanuit een contact start, of de WhatsApp-profielnaam van een onbekend contact. Negeer velden die je niet kent. Een parameter die niet verplicht is en die de assistent niet kent, is null of ontbreekt.

In een eigen body gebruik je de parameters als variabele:

{ "reference": "{{orderNumber}}" }

Geen ingebouwde variabelen

Ingebouwde variabelen zoals {{personNumber}} en {{conversationId}} blijven tijdens het gesprek leeg. Wat vóór het gesprek is opgezocht, krijg je op de meeste telefoongesprekken ook niet mee, dus reken daar niet op. Wil je controleren of de order bij deze klant hoort, maak dan een parameter voor het nummer van de beller, bijvoorbeeld callerNumber met de beschrijving "Het telefoonnummer van de beller". In webchat kent de assistent dat nummer alleen als de bezoeker het noemt.

Het antwoord

Antwoord met een status in de 2xx-reeks, bijvoorbeeld 200, en JSON of gewone tekst. Het antwoord wordt letterlijk aan het AI-model gegeven als resultaat van de tool; de assistent formuleert er zelf een zin van.

{ "status": "shipped", "eta": "2026-09-14", "carrier": "PostNL" }

Gewone tekst werkt ook:

Order A-2231 is op 12 september verzonden met PostNL en wordt op 14 september bezorgd.

• Houd het klein. De assistent krijgt maximaal 6.000 tekens; de rest valt weg. Stuur alleen wat de assistent nodig heeft; geen volledige databaserecords.
• Maak waarden leesbaar. Een datum als 2026-09-14 wordt goed uitgesproken; een Unix-tijdstempel niet.
• Niets gevonden? Antwoord dan met 200 en een duidelijke boodschap, zoals { "found": false, "message": "Geen order met nummer A-2231" }. Zo kan de assistent dit netjes melden en om een ander nummer vragen.
• Bewaar foutstatussen voor echte fouten aan je kant.

Foutafhandeling

Bij een status buiten 2xx hoort de assistent alleen de statuscode; de inhoud van je antwoord krijgt hij niet. Hij verzint dan niets: hij zegt dat hij het niet weet en biedt aan dat het team contact opneemt.

Wij wachten 6 seconden op je endpoint, en dat kun je niet instellen. Antwoordt je endpoint niet op tijd of is het niet bereikbaar, dan hoort de assistent in een tekstgesprek dat het opzoeken is mislukt. Op de meeste telefoongesprekken krijgt hij dan geen enkel resultaat terug en weet hij dus niet dat het verzoek is mislukt. Zorg daarom dat je endpoint ruim op tijd antwoordt. Wij proberen het verzoek niet opnieuw.

De statuscode en het antwoord van een aanroep tijdens het gesprek zie je niet terug in het dashboard. In de Inbox staan bij het gesprek onder Technische details, bij Wat de acties hebben gedaan, alleen de acties na het gesprek. Houd dus een eigen log bij op je endpoint.

Voeg in de Toelichting op het antwoord of op het tabblad Instructies toe wat de assistent moet doen als het opzoeken niet lukt, bijvoorbeeld: "Lukt het opzoeken niet, bied dan aan dat een medewerker terugbelt."

Voorbeeldgesprek

Beller:     Ik wil weten waar mijn bestelling blijft, ordernummer A-2231.
            → POST naar je endpoint: { "orderNumber": "A-2231" }
            ← { "status": "shipped", "eta": "2026-09-14", "carrier": "PostNL" }
Assistent:  Je bestelling A-2231 is verzonden met PostNL en wordt op
            14 september bezorgd. Kan ik nog iets voor je doen?

Alternatief: Google Sheets

Staan de gegevens in een spreadsheet, dan heb je geen eigen endpoint nodig: met de actie Google Sheets zoekt de assistent tijdens het gesprek een rij op. Een webhook is de betere keuze als de gegevens in een CRM, webshop of eigen database staan, of als je eerst iets moet berekenen.

Gerelateerde artikelen

• HTTP-verzoek
• Google Sheets
• Webhooks
• Problemen oplossen: prompt en tools