Tilpassede API-integrasjoner lar chatboten din hente oppdatert informasjon fra ERP-systemet, lageret, CRM-systemet eller en annen tjeneste. De kan også utføre endringer, for eksempel å opprette en avtale. En integrasjon lagrer basis-URL-en; hver operasjon definerer én kjørbar forespørsel. Deretter kobler du utvalgte operasjoner til en chatbot som AI actions (AI-handlinger).
Før du starter
Kontroller at kontoen din inkluderer tilpassede API-integrasjoner. Du trenger endepunktets URL, HTTP-metode, parameternavn og -typer, autentiseringskrav samt et eksempel på et svar. Endepunktet må være tilgjengelig fra ChatLabs servere; localhost på din egen datamaskin er ikke et produksjonsendepunkt.
Bruk HTTPS og en testtjeneste eller testoppføringer under oppsettet. En testforespørsel kaller faktisk opp endepunktet, så en POST, PATCH eller DELETE kan endre eksterne data. Gjør operasjonene trygge å gjenta der det er mulig.
1. Opprett en integrasjon
- Åpne Custom Integrations (Tilpassede integrasjoner) i hovednavigasjonen.
- Klikk på + Define API Integration (+ Definer API-integrasjon).
- Angi API name (API-navn) og API Base URL (API-basis-URL), for eksempel
https://api.example.com. - Klikk på Create API Integration (Opprett API-integrasjon).
- I oppføringen i listen klikker du på View (Vis), og deretter på + Define API Operation (+ Definer API-operasjon).
2. Definer operasjonen
Gi operasjonen en gjenkjennelig etikett og et maskinlesbart Operation name (Operasjonsnavn), for eksempel getProductDetails. Bruk kun bokstaver og tall for operasjonsnavnet, ikke mellomrom eller understreker. Beskriv hva operasjonen gjør, og når chatboten skal bruke den.
Skriv inn den relative URI-en, for eksempel /v1/products/@productId@. Basis-URL-en og URI-en utgjør sammen forespørselsadressen.
Enkelte eksisterende skjermbilder viser eldre eksempelnavn eller plassholdere med klammeparenteser. Følg den gjeldende syntaksen nedenfor: operasjonsnavn som getProductDetails og parameterplassholdere omgitt av @.
Sti- og spørringsparametere
Klikk på Add path variable (Legg til stivariabel) for å definere productId. Angi datatypen og verdikilden, og inkluder deretter @productId@ i URI-en. Stivariabler er obligatoriske, og hver definerte stivariabel må forekomme i URI-en før du kan lagre eller teste.
Bruk Add query parameter (Legg til spørringsparameter) for parametere som limit eller language som hører hjemme etter spørsmålstegnet i URL-en. Angi navnet som API-et ditt forventer, typen, en beskrivelse og verdikilden.
Tilgjengelige verdikilder inkluderer:
- Provided by user or chatbot: modellen henter en verdi fra samtalen. Forklar det forventede formatet, og merk obligatoriske verdier på riktig måte.
- Constant: en verdi som er konfigurert i operasjonen, for eksempel en fast kontoidentifikator eller en begrenset API-nøkkel.
- Random value: en verdi som genereres automatisk.
- Client context: en verdi som sendes av vertsnettstedet, der dette er tilgjengelig for kontoen din. Se Chat API.
Skalære typer inkluderer string, integer, double og boolean. Brødtekstparametere støtter også matriser av typen string og integer.
3. Konfigurer metoden og brødteksten
Velg GET, POST, PUT, PATCH eller DELETE for å samsvare med endepunktet ditt. For andre metoder enn GET tilbyr redigeringsverktøyet forespørselsinnhold av typen raw eller form-data.
For en rå JSON-brødtekst definerer du brødtekstparametere og setter inn plassholderne deres i formatet @name@ i malen. Legg til den nødvendige Content-Type-headeren som kreves av endepunktet ditt. For eksempel med en string-parameter name og en string-array-parameter tags:
{
"name": "@name@",
"tags": @tags@
}
Dette er en mal, ikke bokstavelig JSON før erstatningen finner sted. Plassholdere for matriser må ikke omgis av anførselstegn. Hver definerte brødtekstparameter må brukes i malen når redigeringsverktøyet for rå brødtekst benyttes. Kontroller den genererte forespørselen under testing, inkludert tekst som inneholder anførselstegn eller spesialtegn.
4. Legg til autentiseringsheadere
Bruk Add header (Legg til header) for å definere headerne som forventes av API-et. For et bearer-token bruker du headernavnet Authorization, verdikilden Constant og verdien Bearer YOUR_RESTRICTED_TOKEN.
Hold hemmeligheter unna instruksjoner og URL-er. Unngå operasjoner som returnerer påloggingstokener til modellen og stoler på instruksjoner for å skjule dem. Foretrekk et integrasjonsendepunkt på serversiden som håndterer sin egen autentisering og bare eksponerer den tillatte operasjonen.
5. Lagre og test forespørselen
- Klikk på Save changes (Lagre endringer) i redigeringsverktøyet for operasjonen. I motsetning til vanlige chatbotinnstillinger har dette redigeringsverktøyet en eksplisitt lagreknapp.
- Klikk på Test API Operation (Test API-operasjon). Den er deaktivert så lenge endringene ikke er lagret.
- Angi representative parameterverdier. For testdata i form av matriser bruker du kommaseparerte verdier.
- Kjør testen kun mot data du har autorisasjon til å lese eller endre.
- Undersøk statuskoden, svarteksten, forespørsels-URL-en, headere, brødtekst og eventuelle advarsler som vises i resultatene.
- Rett opp feil, lagre og gjenta etter behov.
Ikke del testutdata som inneholder påloggingsopplysninger. Returner konsise, paginerte data der det er mulig: store svar kan bli avkortet før de når modellen.
6. Koble operasjonen til en chatbot
Åpne chatboten din, og gå deretter til Settings > Actions (Innstillinger > Handlinger). Bruk plussknappen for å legge til en handling, finn operasjonen din under tilpassede API-er, og koble til eller aktiver den. Det å opprette en integrasjon på kontonivå gjør ikke automatisk enhver operasjon tilgjengelig for hver enkelt chatbot.
Gå gjennom handlingens instruksjoner og tilgjengelige sikkerhetsinnstillinger, og vent deretter på bekreftelse om at endringene er lagret. Se AI actions for redigeringsverktøyet for handlinger.
7. Forklar når den skal brukes
Åpne Settings > Role & Behavior (Innstillinger > Rolle og atferd).
Hvis du bruker egendefinerte rolleinstruksjoner, velger du Custom Role Definition (Egendefinert rolledefinisjon) og legger til en presis regel, for eksempel: "Når den besøkende spør om et produkt er på lager, kaller du getProductDetails med tilhørende produkt-ID. Formidle den returnerte tilgjengeligheten. Hvis oppslaget mislykkes, forklarer du at tilgjengeligheten ikke kunne kontrolleres."
Behold chatbotens øvrige nyttige instruksjoner. Vent på bekreftelse om at endringene er lagret, og bruk deretter forhåndsvisningen i Overview (Oversikt) til å teste realistiske spørsmål, manglende parametere, feil og uautoriserte forespørsler. Samtaler i forhåndsvisningen kan utløse reelle operasjoner.
Det er ikke garantert at AI utløser handlingen, eller at den bare kjøres én gang. Test med modellen som er valgt for chatboten din; ikke anta at et modellnavn alene garanterer korrekt verktøybruk.
Sikkerhet og feilsøking
Endepunktet ditt må autentisere forespørsler og autorisere hver enkelt brukers tilgang før sensitiv informasjon returneres eller en endring utføres. En klient-ID, e-postadresse, et ordrenummer eller et kontekstfelt fra nettleseren er ikke tilstrekkelig bevis på identitet. Hvis du sender et brukerspesifikt token via klientkontekst, må serveren din validere det.
Returner kun feltene chatboten faktisk trenger, for eksempel ordrestatus i stedet for en fullstendig kundeprofil. Prompt-instruksjoner kan styre ordlyden, men kan ikke garantere at sensitive data som returneres til modellen, forblir skjult.
Hvis forespørselen lykkes i testverktøyet, men ikke i en samtale, kontrollerer du den tilkoblede handlingen, om den er aktivert, instruksjonene, obligatoriske parametere og tilgjengelig kontekst. Hvis begge deler mislykkes, undersøker du URL-en, HTTP-metoden, autentiseringen, den genererte brødteksten og loggene til endepunktet ditt. Unngå å prøve en skriveoperasjon gjentatte ganger på nytt før du vet om den forrige forespørselen var vellykket.