AI telefoonassistent: API-integraties instellen

Met API-integraties kun je je AI telefoonassistent direct verbinden met externe systemen – bijvoorbeeld met CRM, helpdesk, agenda’s of eigen vakapplicaties. Zo kan de assistent tijdens een lopend gesprek gegevens opvragen (bijv. klantgegevens, ticketstatus) of acties uitvoeren (bijv. ticket aanmaken, lead aanleggen).

Wat zijn API-integraties bij de AI telefoonassistent?

Met de API-functionaliteit kan de AI telefoonassistent tijdens een gesprek via REST-interfaces communiceren met externe systemen.

De assistent kan bijvoorbeeld:

• klantgegevens uit een CRM opvragen (bijv. Salesforce, HubSpot, Pipedrive)
• tickets in een helpdesksysteem aanmaken of de status ervan controleren (bijv. Zendesk, Freshdesk)
• afspraken of resources in agendatools beheren (bijv. Google Calendar, Outlook, Cal.com)
• leads in marketing- of nieuwsbriefsystemen aanmaken (bijv. HubSpot, Mailchimp)

De AI-assistent wordt daarmee van een pure „informatiebron“ een actieve procesbouwsteen in je bedrijfsprocessen.

Typische toepassingsscenario’s en voorbeelden

De volgende tabel toont gangbare toepassingen en het nut van de API-integratie in de praktijk:

Vereisten en technische eisen

Om API-integraties te kunnen gebruiken, moeten de volgende punten vervuld zijn:

• Tarief / product
  Je contract bevat de AI telefoonassistent inclusief API-functionaliteit (momenteel ten minste "AI telefoonassistent Unlimited").

• Toegang tot doelsysteem(en)

  • Actief account in het doelsysteem (bijv. CRM, tickettool, agenda).
  • Rechten om API-keys of tokens aan te maken en te gebruiken.

• Technische basiskennis

  • Begrip van REST-API’s en HTTP-methoden (GET, POST, PUT, DELETE).
  • Basiskennis van JSON (request-body, responses).
  • Kennis van authenticatiemethoden (API-key, bearer-token, basic auth).

• Bereikbaar API-eindpunt

  • Het doelsysteem stelt een publieke REST-API beschikbaar.
  • De eindpunten zijn van buitenaf bereikbaar (geen pure intranet-API’s zonder tunnel/VPN).

Technische werking in een oogopslag

De AI telefoonassistent werkt bij API-integraties als HTTP-client:

1. De assistent voert een gesprek met de beller en verzamelt de benodigde informatie (bijv. klantnummer, e-mailadres, ticket-ID).
2. Deze informatie wordt gevalideerd en gestructureerd aan de hand van een eerder gedefinieerd JSON-schema (Parameters).
3. Daarna wordt een HTTP-request opgebouwd volgens een HAR-definitie (Request Definition) in JSON-formaat.
4. De assistent verstuurt de aanvraag naar de externe API, wacht op het antwoord en gebruikt het resultaat om verder te handelen in het gesprek (bijv. „Ik heb je ticket gevonden, de status is …“).

Centrale onderdelen van de configuratie:

• Tool Name & Description

  • De toolnaam identificeert de integratie.
  • In de beschrijving geef je aan in welke situaties de tool moet worden gebruikt (bijv. „gebruik deze tool als de beller naar een ticketstatus vraagt“).

• Parameters (JSON Schema)

  • Definieert welke invoerwaarden de assistent van de beller moet opvragen (bijv. customerId, date, ticketId).
  • Zorgt ervoor dat alleen volledige en geldige gegevens naar de API worden verzonden.

• Request Definition (HAR JSON)

  • Bevat de URL, HTTP-methode, headers (inclusief authenticatie) en body.
  • Plaatshouders voor de door de assistent opgevraagde parameters worden hier geïnjecteerd.

API-tool toevoegen

1. Log in op de Klantlogin en open de AI telefoonassistent.
2. Ga naar het gedeelte API-integraties.
3. Klik op + Integratie toevoegen.
4. Kies of je:
   • de definitie met behulp van een externe AI-tool wilt aanmaken (Optie A), of
   • de definitie handmatig in expertmodus wilt aanmaken (Optie B).

Optie A: LLM-gestuurde inrichting

In deze optie helpt een externe AI-tool (LLM) je bij het genereren van de HAR-JSON voor de request-definitie.

Om tijd te besparen bij het opstellen van de HAR-syntaxis, kun je de beschikbare prompt gebruiken om de code te laten genereren door een extern Large Language Model (LLM), zoals  Google Gemini, Claude of ChatGPT.

Stap 1: Prompt voor externe LLM kopiëren

1. Open in het gedeelte API-integraties de nieuw aangemaakte tool.
2. Klik op Prompt voor externe LLM kopiëren.
3. De assistent stelt een vooraf gedefinieerde prompt beschikbaar waarin wordt uitgelegd welke API je wilt aanspreken (URL, endpoint, methode enz.).

Stap 2: HAR-JSON met externe AI genereren

1. Open een externe AI-tool naar keuze (bijv. een generatief AI-systeem).
2. Plak de gekopieerde prompt daarin.
3. Vul in de dialoog met de AI alle benodigde details over de doel-API aan (endpoints, parameters, authenticatie).
4. Laat de tool een HAR-object in JSON-formaat genereren dat het gewenste HTTP-request beschrijft.

Stap 3: HAR-definitie invoegen

1. Kopieer het JSON-blok dat door de externe AI-tool is gegenereerd.
2. Ga terug naar het gedeelte API-integraties in de AI telefoonassistent.
3. Plak het JSON-blok in het veld Request Definition (HAR).
4. Vervang indien nodig placeholders voor API-keys / tokens direct in de HAR-JSON door de echte waarden (bijv. in de header Authorization: Bearer <je token>).
5. Klik op Opslaan en daarna bovenaan op Wijzigingen opslaan.

Optie B: Expertmodus (handmatige definitie)

Deze optie is bedoeld voor ontwikkelaars die de benodigde code al hebben of handmatig willen definiëren.

1. Klik rechtsboven in het pop-upvenster op Expertmodus. Er wordt een nieuw pop-upvenster geopend.
2. Vul de vereiste velden in:
   • Naam: Geef een duidelijke, unieke naam op.
   • Beschrijving: Leg vast wanneer de tool door het LLM moet worden geactiveerd.
   • Parameters: Definieer welke parameters de assistent bij de beller moet opvragen; invoer in JSON-formaat.
   • Aanvraag: Definieer de API-aanvraag in HAR-formaat; gebruik voor verwijzingen naar parameters {{ variableName }}; invoer in JSON-formaat.
3. Klik op Opslaan en daarna bovenaan op Wijzigingen opslaan.

Deze beschrijving helpt het bovenliggende AI-model om de juiste tool op het juiste moment te gebruiken.

Integratie testen en fouten oplossen

Na de configuratie moet je elke API-integratie grondig testen:

Testgesprek uitvoeren

• Simuleer typische gespreksscenario’s waarin de tool moet worden geactiveerd (bijv. „Ik wil de status van mijn ticket met ID 12345 weten“).

Antwoorden controleren

• Geeft de assistent zinvolle, consistente antwoorden op basis van de API-terugkoppeling?
• Worden fouten (bijv. „Ticket niet gevonden“, „Klantnummer ongeldig“) correct en vriendelijk gecommuniceerd?

Logs / monitoring gebruiken

• Gebruik, voor zover beschikbaar, log- of monitoringfuncties in je doelsysteem (CRM, helpdesk enz.) om te controleren of aanvragen aankomen en verwerkt worden.
• Bij fouten: analyseer statuscodes (4xx/5xx), foutmeldingen en de request-payload.

Typische foutbronnen:

• Verkeerde of verlopen API-keys / tokens
• Typefouten in URL’s of endpoints
• Inconsistente veldnamen tussen HAR-definitie en JSON-schema
• Ontbrekende verplichte parameters of verkeerde datatypen

Veiligheid en omgaan met API-sleutels

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

Let daarom absoluut op het volgende:

• Geheime gegevens nooit invoeren in externe AI-tools of openbare fora.
• API-sleutels alleen opslaan in de daarvoor bedoelde velden of direct in de HAR-definitie van de AI telefoonassistent.
• API-keys regelmatig roteren en niet langer gebruiken dan nodig.
• Toegangsrechten in het doelsysteem beperken tot het strikt noodzakelijke minimum (least privilege).
• HTTPS (TLS) gebruiken voor alle oproepen, zodat gegevens versleuteld worden verzonden.

Best practices voor stabiele API-integraties

• Klein beginnen, gericht uitbreiden
  Begin met een duidelijk afgebakende toepassing (bijv. ticket aanmaken) en breid later uit met extra functies (ticketstatus, klantgegevens, afspraakplanning).
• Foutsituaties bewust ontwerpen
  Definieer hoe de assistent op veelvoorkomende fouten moet reageren (bijv. „Ticket niet gevonden“, „Verbindingsfout“, „Time-out“).
• Grenzen van de API meenemen
  Controleer de rate limits, quota’s en toegestane aantallen oproepen van je doelsysteem om blokkeringen te voorkomen.
• Datakwaliteit waarborgen
  Valideer invoer via het JSON-schema en vraag bellers indien nodig om bevestiging („Heb ik je klantnummer goed begrepen?“) voordat een request wordt verstuurd.
• Regelmatige reviews
  Controleer je integraties regelmatig:
  • Zijn endpoints of authenticatiemethoden in het doelsysteem gewijzigd?
  • Moeten nieuwe velden of processen worden meegenomen?
• AVG & privacy in acht nemen
  Controleer of het doorgeven van gespreksgegevens aan externe systemen privacyrechtelijk is afgedekt (verwerkersovereenkomst, privacyverklaring, verwijderconcepten).

Verdere artikelen

• Origineel telefoonnummer meesturen bij doorgeschakelde oproepen – Technische aanwijzingen voor doorschakeling
• Belangrijke aanvulling voor je privacyverklaring – Voorbeeldteksten en juridische aanwijzingen
• AI telefoonassistent met installatiewizard instellen – Basisconfiguratie, testgesprek en activering
• Stem, gedrag en bedrijfskennis instellen – Personalisatie en kennisbasis
• Doorschakelen, contacten en verzoeken configureren – Gesprekslogica en routing
• Afspraakplanning instellen (Cal.com & Calendly) – Automatische afspraakplanning