Inleiding:
Met onze REST API kan men een chatbot configureren om te reageren op basis van het resultaat van een API-oproep; via slotvulling, een deel van het API-oproepresultaat gebruiken in een antwoord of een beslissing nemen op basis daarvan.
Wij ondersteunen basistoegang en tokenverificatie; aangepaste headerwaarden, en JSONPath voor het extraheren van entiteiten uit reacties. Om de extractie van jouw reacties met JSONPath te testen, bevelen wij de online tool JSONPath Online Evaluator aan.
Een REST API Call configureren:
Ga naar de pagina om de REST API Call te configureren. Deze pagina vind je door naar Build -> Action -> API Call te gaan. Klik daarna op Create New REST API Call.
- REST API Call Name - Voer een beschrijvende naam in voor deze API-oproep, deze zal worden gebruikt om deze oproep te identificeren wanneer je deze gebruikt in een dialoog.
- Method - De HTTP-methode voor het verzoek. Wij ondersteunen momenteel GET en POST.
- REST API Endpoint URL - Het adres van het verzoek, inclusief het schema (http of https). Als het eindpunt IP-whitelisting vereist, worden de verzoeken verzonden vanaf het IP: 34.90.135.186.
- URL Parameters* - De query string naast de URL.
- Headers* - De request headers. Standaard voegen we automatisch Content-Type: application/json toe aan alle verzoeken.
- Body* - De body van de REST-oproep, d.w.z. de inhoud die naar het eindpunt wordt gestuurd. Dit is alleen beschikbaar voor de POST methode.
- Authorization*- Optioneel authenticatiemechanisme; we ondersteunen momenteel basic en bearer token. Als deze niet voldoen aan het eindpunt, kijk dan of een aangepaste header-invoer zal werken.
De velden met (*) ondersteunen handlebar (dubbele accolades) voor het vullen van sleuven. Deze waarden kunnen worden ingesteld wanneer de API-configuratie wordt gebruikt in het dialoogvenster. - Voor headers kan alleen de waarde worden vervangen door slotvulling.
- Voor Autorisatie kan alleen het Bearer token worden vervangen door slotvulling.
Zodra de vereiste waarden zijn ingevoerd, wordt Test beschikbaar en kunt u de API-aanroep testen:
Vul eventuele handlebar values in voor de test, in dit voorbeeld een categorie van een grap:
En het antwoord op de oproep wordt op het scherm getoond:
Entiteiten halen uit REST API-respons:
Na het succesvol configureren van een API-aanroep, kan het antwoord van de oproep worden gebruikt als entity door gebruik te maken van JSONPath in het API-configuratiescherm. Lees hier meer over JSONPath.
Beschrijving van de velden onder Extraction Rules:
- Entity: De naam van de entity om de gewonnen waarde op te slaan.
- Extraction Path (JSONPath): De JSONPath-expressie om de entity uit te halen
In het bovenstaande voorbeeld zal de grap worden ingesteld op "After meals, Chuck Norris picks his teeth with a bowie knife". Deze grap zal beschikbaar zijn als een entity voor het vullen van slots in dialogen.
JSONPath Online Evaluator kan worden gebruikt om extractie pad expressies te testen. Om het bovenstaande antwoord te testen, plakt je het antwoord in de linkerkolom, en test je jouw expressies in de invoerbalk en controleer of de geëxtraheerde waarde in de juiste kolom wordt verwacht:
Klik hier voor meer informatie over JSONPath.
API-nodes gebruiken:
De API die je hebt toegevoegd in OBI Bots, kun je in een API turn toevoegen om er gebruik van te maken. Dit doe je door naar de dialoog te gaan waar die gebruikt dient te worden en een action turn toe te voegen. Bij choose type of action kies je voor api.
- Selecteer de API die je wilt gebruiken uit de dropdown.
- De lijst met te vullen handvatten (dubbele accolades) wordt hieronder getoond. Deze komen overeen met de slots die moeten worden gevuld vanuit de API-configuratie.
- Voer voor elk daarvan de gewenste waarde in. Handlebars worden hier ook ondersteund als de waarden moeten worden gevuld uit eerder gevulde slots; of gewoon een letterreeks zoals het voorbeeld hierboven.
Van daaruit kan er verwezen worden naar de waarden die zijn opgehaald uit de API-aanroep. Bijvoorbeeld, in een reply turn:
Voorbeeld: Op token gebaseerde authenticatie
Doel
In dit voorbeeld zullen we een chatbot configureren die zal inloggen op het OBI Bots platform met een vooraf geconfigureerde gebruikersnaam en wachtwoord.
! Als je problemen hebt met het volgen van deze stappen met niet genoeg intents om te trainen, maak dan gewoon een user turn in een andere dialoog, bijvoorbeeld in de Fallback dialog. Dit komt omdat in dit voorbeeld geen user turns worden verwerkt en het dus geen realistische chatbot is die het systeem verwacht.
Login API configuratie
Eerst moeten we een API-configuratie maken die inlogt en het toegangstoken uit het antwoord haalt. Met het toegangstoken kunnen we verdere API-aanroepen doen als de ingelogde gebruiker.
Na een testoproep doen we een JSON pad-expressie om het toegangstoken te extraheren:
Huidige gebruiker API-configuratie ophalen:
Vervolgens willen we de weergavenaam van de gebruiker met het gegeven in de bovenstaande stap. We zullen het bovenstaande toegangstoken gebruiken als draagtoken.
We gebruiken huur krulhaakjes om aan te geven dat we de waarde van een entiteit hier moeten gebruiken via het vullen van slots. De entiteit wordt vastgelegd in de eerder geconfigureerde login-aanroep. Als jouw API een lang levend token gebruikt, kun je dat hier plakken en de aanmeldingsoproep volledig overslaan.
Vervolgens halen we de weergavenaam uit het antwoord:
Dialoog
Om dit voorbeeld te illustreren, maken we een dialoog als volgt:
We dienen eerst de login-oproep te gebruiken, omdat deze de access_token ophaalt en beschikbaar maakt voor volgende oproepen. Deze aanroep moet volledig verborgen blijven voor de chatgebruiker.
De eerste API beurt ziet er als volgt uit:
Het wordt gevolgd door een voorwaardelijke controle om er zeker van te zijn dat het inloggen is gelukt en dat we daadwerkelijk een token hebben kunnen ophalen. Dit is niet strikt noodzakelijk, maar enige vorm van foutafhandeling is altijd aan te bevelen.
Hier controleren we of de access_token entiteit die we uit de eerste API-aanroep willen halen ook echt bestaat. Indien de aanmelding niet lukt, zal de bot het gesprek verder leiden naar de "No Conditional Match".
Vervolgens doen we de tweede API-aanroep. We moeten de eerder verkregen access_token gebruiken in deze oproep, en dus configureren we het als volgt:
En tenslotte laten we de bot reageren door je naam te zeggen:
Testen
Als je geen gebruikersnaam hebt ingesteld, vertelt de bot natuurlijk gewoon jouw e-mailadres.
Voorbeeld: TheCocktailDB API
Doel
Hier zullen we een chatbot maken die de naam van een door de gebruiker ingevoerde drank accepteert en er informatie over zoekt in een gratis cocktaildatabase. De verstrekte informatie moet de ingrediënten en de bereidingswijze van het drankje bevatten.
API configuratie
Onze API Call moet worden ingesteld om het antwoord van de gebruiker als een search_string parameter te nemen:
Vervolgens halen we de vereiste informatie uit de respons door middel van JSON path expressions.
Dialoog
Laten we een simpel dialoog bouwen met een user turn die de intent cocktail.info bevat en de entity cocktail.name om de invoer vast te leggen:
In de volgende action turn geven we onze entity valye door als API request parameter:
En de laatste stap is om te antwoorden met de verzamelde informatie in de bot turn:
Testen
Zorg ervoor dat de chatbot is getraind en controleer vervolgens de resultaten: