AI telefoonassistent: API-integraties instellen

Met API-integraties koppel je je AI telefoonassistent aan externe systemen, bijvoorbeeld een crm, een helpdesk, agenda's of eigen bedrijfsapplicaties. Zo kan de assistent tijdens een gesprek gegevens opvragen (bijvoorbeeld klantgegevens of de status van een ticket) of acties uitvoeren (bijvoorbeeld een ticket aanmaken of een lead registreren).

Wat zijn API-integraties en waarvoor gebruik ik ze?

De assistent kan tijdens een gesprek via REST-interfaces met externe systemen communiceren. Zo wordt hij van een assistent die alleen informatie geeft een actief onderdeel van je bedrijfsprocessen. Typische toepassingen:

Tip: gebruik API-integraties eerst voor één of twee duidelijk afgebakende processen, bijvoorbeeld het aanmaken van tickets of het registreren van leads. Breid later uit als de basis stabiel werkt.

Voor het koppelen van een agenda of boekingstool is er een aparte instelling: zie AI telefoonassistent: afspraken boeken instellen.

Welke voorwaarden gelden?

• Je tarief bevat de uitgebreide API-integratie (zie hierboven).
• Je hebt een actief account in het doelsysteem (bijvoorbeeld crm, ticketsysteem of agenda) en mag daar API-sleutels of tokens aanmaken.
• Je kent de basis van REST-API's en HTTP-methoden (GET, POST, PUT, DELETE), JSON en de authenticatiemethoden van het doelsysteem (API-sleutel, bearer token, basic auth).
• Het doelsysteem biedt een openbaar bereikbare REST-API. Alleen intranet-API's zonder tunnel of VPN zijn niet bereikbaar.

Hoe werkt een API-integratie?

Bij API-integraties werkt de assistent als HTTP-client:

1. Hij voert het gesprek en vraagt de benodigde informatie, bijvoorbeeld klantnummer, e-mailadres of ticketnummer.
2. Hij controleert die gegevens aan de hand van de parameters (JSON-schema) die jij hebt vastgelegd.
3. Hij bouwt het verzoek op volgens je verzoek-definitie (HAR-formaat) en stuurt het naar de externe API.
4. Hij gebruikt het antwoord om het gesprek voort te zetten, bijvoorbeeld: "Ik heb je ticket gevonden, de status is …".

Een integratie bestaat uit:

Hoe voeg ik een API-integratie toe?

1. Open in je klantenlogin het pakket met je AI-assistenten. Klik op de pagina Overzicht op de kaart AI Frontdesk. De interface opent in een nieuw browsertabblad.
2. Open in de navigatie links onder Instellingen het onderdeel API-integraties.
3. Klik op Integratie toevoegen.
4. Kies hoe je de integratie aanmaakt:
   • LLM-ondersteund (optie A): een AI-tool helpt je bij het aanmaken.
   • Expertmodus (optie B): je definieert de integratie zelf. Met Expertmodus of LLM-ondersteund rechtsboven in het venster wissel je tussen beide.
5. Klik op Toepassen en daarna rechtsboven op Opslaan.

Optie A: LLM-ondersteund

1. Klik bij Stap 1 op Openen in ChatGPT. Via het pijltje ernaast kies je in plaats daarvan Openen in Claude, of kopieer je met Prompt kopiëren de voorbereide prompt om hem in een AI-tool naar keuze te plakken (bijvoorbeeld Gemini).
2. Beschrijf aan de AI-tool de API die je wilt aanspreken (URL, eindpunt, methode, benodigde gegevens).
3. Laat de kant-en-klare integratie als JSON weergeven.
4. Kopieer het JSON-antwoord en plak het bij Stap 2 in het veld.
5. Klik op Toepassen.

Optie B: Expertmodus

1. Klik rechtsboven in het venster op Expertmodus.
2. Vul de velden in:
   • Naam, bijvoorbeeld ticket_status
   • Beschrijving: wanneer de assistent de integratie moet gebruiken
   • Parameters in JSON-formaat. Let op juiste gegevenstypen (string, number, boolean), zinvolle verplichte velden (required) en eventueel beperkingen, bijvoorbeeld een patroon voor ID's.
   • Verzoek in HAR-formaat. Met {{ variableName }} verwijs je naar parameters.
3. Klik op Toepassen.

Voorbeeld: ticketstatus opvragen

Parameters:

{
  "type": "object",
  "properties": {
    "ticketId": { "type": "string", "description": "Ticketnummer van de beller" }
  },
  "required": ["ticketId"]
}

Verzoek:

{
  "method": "GET",
  "url": "https://api.example.com/tickets/{{ ticketId }}"
}

Welke systeemvariabelen kan ik gebruiken?

Systeemvariabelen zijn beschikbaar in elk verzoek. Je hoeft ze niet als parameter te declareren: voeg ze direct toe in de URL, de headers of de body van je verzoek. In het venster Integratie toevoegen vind je ze onder Systeemvariabelen.

Voorbeeld: beller en gesprek melden aan een extern systeem

{
  "method": "POST",
  "url": "https://api.example.com/calls",
  "headers": [{ "name": "Content-Type", "value": "application/json" }],
  "postData": {
    "mimeType": "application/json",
    "text": "{\"callId\": \"{{ system_conversation_id }}\", \"caller\": \"{{ system_caller_number }}\"}"
  }
}

Hoe test ik de integratie en los ik fouten op?

1. Klik rechtsboven op Testgesprek en speel een typisch gesprek na waarin de integratie moet worden gebruikt, bijvoorbeeld: "Ik wil graag de status van mijn ticket met ID 12345 weten."
2. Controleer of de assistent zinvol reageert op het antwoord van de API en fouten zoals "ticket niet gevonden" vriendelijk communiceert.
3. Gebruik de logboeken van je doelsysteem (crm, helpdesk) om te controleren of de verzoeken aankomen. Kijk bij fouten naar statuscodes (4xx/5xx), foutmeldingen en de verzonden gegevens.

Veelvoorkomende oorzaken van fouten:

• onjuiste of verlopen API-sleutels of tokens
• typefouten in URL's of eindpunten
• veldnamen die niet overeenkomen tussen parameters en verzoek
• ontbrekende verplichte parameters of verkeerde gegevenstypen

Hoe ga ik veilig om met API-sleutels?

API-sleutels en tokens zijn gevoelige toegangsgegevens waarmee derden toegang tot je systemen kunnen krijgen.

• Voer geheime gegevens nooit in externe AI-tools of openbare fora in.
• Bewaar API-sleutels alleen in de daarvoor bedoelde velden, dus in het verzoek van je integratie.
• Vernieuw API-sleutels regelmatig en gebruik ze niet langer dan nodig.
• Beperk de toegangsrechten in het doelsysteem tot het strikt noodzakelijke.
• Gebruik voor alle aanroepen HTTPS (TLS).
• Bij vermoeden van misbruik: blokkeer of verwijder de sleutel direct in het doelsysteem, maak een nieuwe en werk het verzoek van je integratie bij.

Welke tips gelden voor stabiele integraties?

• Begin klein: start met één duidelijk afgebakende toepassing en breid later uit.
• Ontwerp foutsituaties bewust: bepaal hoe de assistent op fouten moet reageren, bijvoorbeeld bij "ticket niet gevonden", "verbindingsfout" of "time-out".
• Houd rekening met de grenzen van de API: controleer rate limits en toegestane aantallen aanroepen van je doelsysteem.
• Zorg voor goede gegevenskwaliteit: valideer invoer via het JSON-schema en vraag bellers eventueel om bevestiging, bijvoorbeeld: "Heb ik je klantnummer goed begrepen?".
• Controleer regelmatig: zijn eindpunten of authenticatie in het doelsysteem gewijzigd? Moeten nieuwe velden worden meegenomen?
• Denk aan privacy: controleer of het doorgeven van gespreksgegevens aan externe systemen onder je privacyregels valt (verwerkersovereenkomst, privacyverklaring, bewaartermijnen).

Verwante artikelen

• AI Frontdesk: overzicht van alle assistenten
• AI telefoonassistent instellen en activeren
• AI telefoonassistent: afspraken boeken instellen
• AI telefoonassistent: doorschakelen & aanvragen
• AI telefoonassistent: stem, gedrag & kennis