Aangepaste API-integraties stellen je chatbot in staat om live informatie op te vragen uit je ERP, magazijnsysteem, CRM of een andere dienst. Ze kunnen ook wijzigingen doorvoeren, zoals het aanmaken van een afspraak. Een integratie slaat de basis-URL op; elke operatie definieert één aanroepbaar verzoek. Vervolgens koppel je de geselecteerde operaties aan een chatbot als AI actions.
Voordat je begint
Controleer of jouw account aangepaste API-integraties ondersteunt. Je hebt de URL van het eindpunt nodig, de HTTP-methode, parameternamen en -typen, authenticatievereisten en een voorbeeldrespons. Het eindpunt moet bereikbaar zijn vanaf de servers van ChatLab; localhost op je computer is geen productie-eindpunt.
Gebruik HTTPS en een testomgeving of testgegevens voor de configuratie. Een testverzoek roept het eindpunt daadwerkelijk aan, dus een POST, PATCH of DELETE kan externe gegevens wijzigen. Zorg er waar mogelijk voor dat operaties veilig herhaald kunnen worden.
1. Een integratie aanmaken
- Open Custom Integrations (Aangepaste integraties) in de hoofdnavigatie.
- Klik op + Define API Integration (+ API-integratie definiëren).
- Voer de API name (API-naam) en API Base URL (API-basis-URL) in, bijvoorbeeld
https://api.example.com. - Klik op Create API Integration (API-integratie aanmaken).
- Klik in het overzicht bij de betreffende integratie op View (Bekijken), en vervolgens op + Define API Operation (+ API-operatie definiëren).
2. De operatie definiëren
Geef de operatie een herkenbaar label en een machineleesbare Operation name (Operatienaam), zoals getProductDetails. Gebruik uitsluitend letters en cijfers voor de operatienaam, geen spaties of underscores. Beschrijf wat de operatie doet en wanneer de chatbot deze moet gebruiken.
Voer de relatieve URI in, bijvoorbeeld /v1/products/@productId@. De basis-URL en de URI vormen samen het adres van het verzoek.
Sommige bestaande schermafbeeldingen tonen oudere voorbeeldnamen of tijdelijke aanduidingen tussen accolades. Volg de actuele syntaxis zoals hieronder beschreven: operatienamen zoals getProductDetails en tijdelijke aanduidingen voor parameters omsloten door @.
Pad- en queryparameters
Klik op Add path variable (Padvariabele toevoegen) om productId te definiëren. Stel het gegevenstype en de waardebron in, en neem vervolgens @productId@ op in de URI. Padvariabelen zijn verplicht, en elke gedefinieerde padvariabele moet in de URI voorkomen voordat je kunt opslaan of testen.
Gebruik Add query parameter (Queryparameter toevoegen) voor parameters zoals limit of language die achter het vraagteken van de URL horen. Voer de naam in die jouw API verwacht, het type, een beschrijving en de waardebron.
Beschikbare waardebronnen zijn onder meer:
- Provided by user or chatbot: het model levert een waarde op basis van het gesprek. Licht het verwachte formaat toe en markeer verplichte waarden op de juiste manier.
- Constant: een waarde die in de operatie is geconfigureerd, zoals een vast account-ID of een beperkt API-authenticatiegegeven.
- Random value: een automatisch gegenereerde waarde.
- Client context: een waarde die wordt doorgegeven door de host-website, indien beschikbaar voor jouw account. Zie Chat API.
Scalaire typen zijn onder meer string, integer, double en boolean. Body-parameters ondersteunen ook arrays van strings en integers.
3. De methode en body configureren
Kies GET, POST, PUT, PATCH of DELETE overeenkomstig jouw eindpunt. Voor andere methoden dan GET biedt de editor raw of form-data als inhoud voor het verzoek.
Definieer voor een raw JSON-body de body-parameters en voeg de bijbehorende tijdelijke aanduidingen @name@ in het sjabloon in. Voeg de juiste Content-Type-header toe die door je eindpunt vereist is. Bijvoorbeeld met de parameters name (string) en tags (string-array):
{
"name": "@name@",
"tags": @tags@
}
Dit is een sjabloon en geen letterlijke JSON tot de waarden zijn ingevuld. Tijdelijke aanduidingen voor arrays mogen niet tussen aanhalingstekens staan. Elke gedefinieerde body-parameter moet in het sjabloon worden gebruikt wanneer de raw-body-editor van toepassing is. Controleer het gegenereerde verzoek tijdens het testen, inclusief tekst met aanhalingstekens of speciale tekens.
4. Authenticatieheaders toevoegen
Gebruik Add header (Header toevoegen) om de headers te definiëren die door de API worden verwacht. Gebruik voor een bearer-token de headernaam Authorization, waardebron Constant, en de waarde Bearer YOUR_RESTRICTED_TOKEN.
Houd geheimen buiten prompts en URL's. Vermijd operaties die inlogtokens terugsturen naar het model en vertrouw niet op instructies om deze verborgen te houden. Gebruik bij voorkeur een server-side integratie-eindpunt dat zijn eigen authenticatie beheert en alleen de toegestane operatie beschikbaar stelt.
5. Het verzoek opslaan en testen
- Klik op Save changes (Wijzigingen opslaan) in de operatie-editor. In tegenstelling tot de normale instellingen van de chatbot heeft deze editor een expliciete opslagknop.
- Klik op Test API Operation (API-operatie testen). Deze knop is uitgeschakeld zolang er niet-opgeslagen wijzigingen zijn.
- Voer representatieve parameterwaarden in. Gebruik voor array-testinvoer door komma's gescheiden waarden.
- Voer de test alleen uit met gegevens die je bevoegd bent te lezen of te wijzigen.
- Controleer de statuscode, de respons-body, de verzoek-URL, de headers, de body en eventuele waarschuwingen in de resultaten.
- Corrigeer fouten, sla op en herhaal indien nodig.
Deel geen testuitvoer die inloggegevens bevat. Zorg waar mogelijk voor gerichte, gepagineerde gegevens: grote responsen kunnen worden afgekapt voordat ze het model bereiken.
6. De operatie koppelen aan een chatbot
Open je chatbot en ga naar Settings > Actions (Instellingen > Acties). Gebruik de plusknop om een actie toe te voegen, zoek je operatie onder de aangepaste API's en koppel of activeer deze. Het aanmaken van een integratie op accountniveau zorgt er op zichzelf niet voor dat elke operatie direct beschikbaar is voor elke chatbot.
Controleer de instructies van de actie en de beschikbare beveiligingsinstellingen, en wacht tot de status aangeeft dat alles is opgeslagen. Zie AI actions voor de actie-editor.
7. Uitleggen wanneer de operatie moet worden gebruikt
Open Settings > Role & Behavior (Instellingen > Rol en gedrag).
Als je aangepaste rolinstructies gebruikt, selecteer dan Custom Role Definition (Aangepaste roldefinitie) en voeg een nauwkeurige regel toe, bijvoorbeeld: "Wanneer de bezoeker vraagt of een product op voorraad is, roep dan getProductDetails aan met het bijbehorende product-ID. Meld de geretourneerde beschikbaarheid. Als het opzoeken mislukt, leg dan uit dat de beschikbaarheid niet kon worden gecontroleerd."
Behoud de overige nuttige instructies van de chatbot. Wacht tot de opgeslagen status verschijnt en gebruik vervolgens het voorbeeldvenster in Overview (Overzicht) om realistische vragen, ontbrekende parameters, fouten en ongeautoriseerde verzoeken te testen. Gesprekken in het voorbeeldvenster kunnen daadwerkelijke operaties uitvoeren.
Het aanroepen door de AI is niet gegarandeerd en gebeurt niet noodzakelijk slechts één keer. Test met het model dat voor jouw chatbot is geselecteerd; ga er niet van uit dat een modelnaam alleen al garant staat voor een correct gebruik van de functies.
Beveiliging en probleemoplossing
Je eindpunt moet verzoeken verifiëren en de toegang van elke gebruiker autoriseren voordat gevoelige informatie wordt geretourneerd of een wijziging wordt uitgevoerd. Een door de browser aangeleverde client-ID, e-mailadres, bestelnummer of contextveld is geen afdoende bewijs van identiteit. Als je een token per gebruiker doorgeeft via de clientcontext, moet je server dit valideren.
Retourneer alleen de velden die de chatbot nodig heeft, zoals een bestelstatus in plaats van een volledig klantprofiel. Promptinstructies kunnen helpen bij de formulering, maar kunnen niet garanderen dat gevoelige gegevens die naar het model worden gestuurd verborgen blijven.
Als het verzoek slaagt in de testomgeving maar niet tijdens een gesprek, controleer dan de gekoppelde actie, of deze is ingeschakeld, de instructies, verplichte parameters en de beschikbare context. Als beide mislukken, controleer dan de URL, de HTTP-methode, de authenticatie, de gegenereerde body en de logboeken van je eindpunt. Vermijd het herhaaldelijk opnieuw proberen van een schrijfbewerking totdat je zeker weet of het vorige verzoek al dan niet is geslaagd.