Live gegevens opzoeken tijdens een gesprek

Met de skill API Aanroepen kan je agent op een van drie momenten in een gesprek informatie naar een extern systeem sturen of daar ophalen: voor, tijdens of na het gesprek.

Dit artikel gaat over de modus tijdens het gesprek. Daarbij start de agent midden in een lopend gesprek een API-verzoek op basis van wat de beller heeft gezegd, wacht op het antwoord en gebruikt het resultaat op een natuurlijke manier in zijn volgende antwoord.

Voor API-aanroepen voor het gesprek (bijvoorbeeld een beller opzoeken) of na het gesprek (bijvoorbeeld vastleggen in je CRM), zie API Aanroepen — voor en na het gesprek.

Wanneer je hem gebruikt

Gebruik deze modus als je agent:

• live gegevens moet opzoeken op basis van wat de beller net zei (bestelstatus, saldo, beschikbaarheid)
• informatie tijdens het gesprek moet controleren (geldigheid van een lidmaatschap, boekingsnummer, ID)
• een waarde moet berekenen of ophalen om aan de beller voor te lezen (offerte, prijsindicatie, levertijd)
• een automatisering moet starten in Make.com, n8n, Zapier of een eigen endpoint terwijl de beller nog aan de lijn is

Zijn de gegevens al voor het gesprek beschikbaar (of hoeven ze pas na het gesprek verstuurd te worden), gebruik dan Pre Call of Post Call.

Zo werkt het

Ziet de agent het juiste moment, op basis van je instructies in het Hoofddoel en de beschrijving van de skill, dan stuurt hij een HTTP-verzoek naar de URL die je opgeeft, wacht op het antwoord en gebruikt het resultaat in zijn antwoord.

Je bepaalt:

• Het endpoint: URL en HTTP-methode (GET of POST)
• Parameters: wat er in het verzoek wordt meegestuurd
• Headers: authenticatietokens of eigen headers, als dat nodig is
• Results: welke velden uit het antwoord de agent mag zien en gebruiken (alleen in deze modus)

Instellen

1. Ga naar Agent → Vaardigheden en voeg een skill toe.
2. Kies API Aanroepen.
3. Stel de velden in:
   • Uitvoeringsvolgorde: tijdens het gesprek
   • Actienaam: een duidelijke naam in snake_case, zoals check_order_status. In het Hoofddoel gebruik je hem als {{actienaam}}.
   • Beschrijving: een korte zin over wat de actie doet. De agent leest die om te bepalen wanneer hij de actie gebruikt.
   • API-endpoint: de volledige URL van je endpoint
   • Methode: GET of POST
   • Parameters (optioneel): waarden die met het verzoek worden meegestuurd; zie "Parameters" hieronder
   • Results (optioneel): welke velden uit het antwoord de agent mag zien; zie "Results en Path" hieronder
   • Headers (optioneel): autorisatietokens of eigen headers. Webhook-endpoints van Make.com, n8n of Zapier hebben meestal geen authenticatie nodig; laat dit veld dan leeg.
4. Schakel de skill in met de schakelaar.
5. Klik op Creëren.

Parameters: vast of dynamisch

Elke parameter heeft een naam en een beschrijving. Dezelfde interface dekt twee verschillende situaties.

Vaste parameters

De agent stuurt altijd dezelfde waarde. Zet de waarde zelf in de beschrijving.

De gegevens naar je endpoint bevatten dan altijd "source": "voice_agent".

Dynamische parameters

De agent moet een waarde uit het gesprek halen en meesturen. De beschrijving vertelt de agent waar hij op moet letten; het Hoofddoel vertelt hem wanneer hij de actie gebruikt.

Fragment uit het Hoofddoel:

Wil de beller zijn leverstatus weten, vraag dan naar zijn bestelnummer en roep {{check_order_status}} aan. Vertel hem daarna de status en de verwachte leverdatum.

Results en Path

Het onderdeel Results is optioneel en bepaalt hoe de agent je API-antwoord leest.

• Leeg laten: de agent krijgt het hele antwoord en kan elk veld via zijn naam in het Hoofddoel gebruiken, ook geneste velden. Makkelijk in te stellen, maar minder controle.
• Results-items toevoegen: alleen de gekoppelde velden zijn zichtbaar voor de agent. Al het andere blijft verborgen, handig om debuginformatie, interne vlaggen of gevoelige gegevens buiten het gesprek te houden.

Elk Results-item heeft drie velden:

• Naam: de variabelenaam die je in het Hoofddoel gebruikt, zoals {{customer_name}}
• Path: de plek van de waarde in het JSON-antwoord, met puntnotatie voor geneste velden
• Beschrijving: wat het veld betekent; helpt de agent het goed te gebruiken in het gesprek

Voorbeeld

Geeft je endpoint dit terug:

{
  "customer": {
    "name": "Ferguson",
    "member_tier": "Gold"
  },
  "internal": {
    "secret_code": "XYZ-9921"
  },
  "debug_info": "ignore me"
}

En stel je dit in:

Dan kan de agent {{customer_name}}, {{member_tier}} en {{secret_code}} in de prompt gebruiken. Het veld debug_info blijft volledig verborgen, omdat het niet is gekoppeld.

Puntnotatie

• Voor velden op het hoogste niveau gebruik je direct de veldnaam: status
• Voor geneste velden gebruik je puntnotatie: customer.membership.tier
• Elk Results-item koppelt precies één waarde

Het Hoofddoel schrijven

Omdat de actie tijdens het gesprek draait, moet je de agent duidelijk vertellen wanneer hij hem start en hoe hij het antwoord gebruikt. Een goede instructie bevat:

1. De trigger: wat de beller moet zeggen of willen
2. De actienaam: welke actie wordt aangeroepen
3. Wat er met het resultaat gebeurt: welke velden worden voorgelezen en wat er wordt gezegd

Voorbeeld:

Vraagt de beller naar zijn levering, vraag dan naar zijn bestelnummer en roep {{check_order_status}} aan. Vertel hem de pakketstatus met {{status}} en de verwachte aankomst met {{estimated_delivery_date}}.

Voorbeeld: zending volgen

Scenario: de beller vraagt "waar is mijn pakket?"

Configuratie:

• Uitvoeringsvolgorde: tijdens het gesprek
• Actienaam: check_order_status
• Beschrijving: zendinginformatie van een bestelling ophalen
• API-endpoint: https://api.shippingcompany.com/tracking
• Methode: GET
• Parameter: order_number (beschrijving: "het bestelnummer dat de beller noemt")
• Results:

Fragment uit het Hoofddoel:

Vraagt de beller naar zijn pakket of levering, vraag dan naar zijn bestelnummer en roep check_order_status aan. Beantwoord de vraag duidelijk met {{status}} en {{estimated_delivery_date}}.

Zo verloopt het gesprek:

Beller: "Waar is mijn pakket?"

Agent: "Natuurlijk, kun je me je bestelnummer geven?"

Beller: "Dat is 4471."

(De agent roept de API in realtime aan.)

Agent: "Je pakket is onderweg en wordt naar verwachting op 24 oktober bezorgd."

Andere voorbeelden

Lidmaatschap controleren:

Noemt de beller zijn lidnummer, roep dan check_membership_status aan om te controleren of zijn account actief is. Vertel het hem met {{membership_status}}.

Prijs opvragen:

Vraagt de beller om een offerte, vraag dan welk product en hoeveel hij nodig heeft en roep get_price_estimate aan. Lees {{estimated_price}} aan hem voor.

Live beschikbaarheid:

Vraagt de beller of een product op voorraad is, vraag dan naar de productnaam en roep check_stock aan. Vertel hem {{stock_status}} en, als het beschikbaar is, {{quantity_available}}.

Goed om te weten

Lege Results betekent: de agent ziet alles

Voeg je geen Results-items toe, dan leest de agent het hele antwoord. Wil je bepaalde velden verbergen, dan moet je Results bewust instellen en alleen koppelen wat zichtbaar mag zijn.

Geen ingebouwde foutafhandeling

Reageert je endpoint niet, geeft het een fout terug of stuurt het lege velden, dan heeft de skill geen ingebouwd alternatief. De agent heeft dan gewoon geen gegevens en valt misschien stil, vraagt om herhaling of verzint in sommige gevallen iets.

Voeg altijd expliciete instructies voor dit geval toe aan je Hoofddoel:

Vertel de beller zijn bestelstatus met {{status}}. Heb je die informatie niet, bied dan je excuses aan en bied aan om per e-mail op te volgen.

Terugvalinstructies moeten concreet zijn. Vage terugvalinstructies leiden tot vage verzinsels.

Wachttijd beïnvloedt het gesprek

De agent moet op het antwoord van je endpoint wachten voordat hij verdergaat. Trage endpoints zorgen voor ongemakkelijke stiltes. Streef naar antwoorden binnen een seconde en gebruik de modus Pre Call als de gegevens al aan het begin van het gesprek nodig zijn.

Authenticatie

Heeft je endpoint authenticatie nodig, voeg de inloggegevens dan toe in het veld Headers (bijvoorbeeld Authorization: Bearer your-token-here). Veel webhookdiensten hebben geen headers nodig; laat dat veld dan leeg.

In de modus tijdens het gesprek krijgt je agent live toegang tot je systemen: hij kan informatie ophalen, gegevens controleren of acties in realtime uitvoeren terwijl het gesprek natuurlijk blijft. Het komt erop aan precies te bepalen welke velden de agent mag zien (Path) en hem duidelijke instructies te geven voor zowel succes als mislukking (Hoofddoel).