Brugerdefinerede API-integrationer

Brugertilpassede API-integrationer giver din chatbot mulighed for at hente live-oplysninger fra dit ERP, lager, CRM eller en anden tjeneste. De kan også udføre ændringer, såsom at oprette en aftale. En integration gemmer basis-URL'en; hver handling definerer en kaldbar anmodning. Derefter knytter du udvalgte handlinger til en chatbot som AI actions.

Før du går i gang

Kontrollér, at din konto omfatter brugertilpassede API-integrationer. Du skal bruge slutpunktets URL, HTTP-metode, parameternavne og -typer, godkendelseskrav samt et eksempelsvar. Slutpunktet skal være tilgængeligt fra ChatLabs servere; localhost på din computer er ikke et produktionsslutpunkt.

Brug HTTPS og en testtjeneste eller testdata under opsætningen. En testanmodning foretager et reelt kald til slutpunktet, så en POST-, PATCH- eller DELETE-handling kan ændre eksterne data. Gør så vidt muligt handlingerne sikre at gentage.

1. Opret en integration

1. Åbn Custom Integrations (Brugertilpassede integrationer) i hovednavigationen.
2. Klik på + Define API Integration (+ Definer API-integration).
3. Indtast API name (API-navn) og API Base URL (API-basis-URL), for eksempel https://api.example.com.
4. Klik på Create API Integration (Opret API-integration).
5. I listens post skal du klikke på View (Vis) og derefter + Define API Operation (+ Definer API-handling).

2. Definer handlingen

Giv handlingen en genkendelig etiket og et maskinlæsbart Operation name (Handlingsnavn), såsom getProductDetails. Brug kun bogstaver og tal til handlingsnavnet, ikke mellemrum eller understregninger. Beskriv, hvad handlingen gør, og hvornår chatbotten skal bruge den.

Indtast den relative URI, for eksempel /v1/products/@productId@. Basis-URL'en og URI'en danner anmodningens adresse.

Nogle eksisterende skærmbilleder viser ældre eksempelnavne eller pladsholdere med tuborgklammer. Følg den aktuelle syntaks nedenfor: handlingsnavne som getProductDetails og parameterpladsholdere omgivet af @.

Sti- og forespørgselsparametre

Klik på Add path variable (Tilføj stivariabel) for at definere productId. Angiv dens datatype og værdikilde, og indsæt derefter @productId@ i URI'en. Stivariabler er påkrævede, og enhver defineret stivariabel skal optræde i URI'en, før du kan gemme eller teste.

Brug Add query parameter (Tilføj forespørgselsparameter) til parametre som limit eller language, der hører til efter URL'ens spørgsmålstegn. Indtast det navn, dit API forventer, dets type, beskrivelse og værdikilde.

Tilgængelige værdikilder omfatter:

• Provided by user or chatbot: modellen leverer en værdi fra samtalen. Forklar det forventede format, og markér påkrævede værdier korrekt.
• Constant: en værdi konfigureret i handlingen, såsom et fast konto-id eller begrænset API-adgangskode.
• Random value: en værdi, der genereres automatisk.
• Client context: en værdi overført af værtswebstedet, hvor dette er tilgængeligt for din konto. Se Chat API.

Skalære typer omfatter string, integer, double og boolean. Brødtekstparametre understøtter også string- og integer-arrays.

3. Konfigurer metode og brødtekst

Vælg GET, POST, PUT, PATCH eller DELETE, så det matcher dit slutpunkt. Ved andre metoder end GET tilbyder editoren raw eller form-data anmodningsindhold.

Ved en rå JSON-brødtekst skal du definere brødtekstparametrene og indsætte deres @name@-pladsholdere i skabelonen. Tilføj den relevante Content-Type-header, som dit slutpunkt kræver. For eksempel med en string-parameter name og en string-array-parameter tags:

{
  "name": "@name@",
  "tags": @tags@
}

Dette er en skabelon, ikke bogstavelig JSON før erstatningen finder sted. Array-pladsholdere må ikke omgives af citationstegn. Hver defineret brødtekstparameter skal bruges i skabelonen, når editoren til rå brødtekst anvendes. Kontrollér den genererede anmodning under test, herunder tekst med citationstegn eller specialtegn.

4. Tilføj godkendelsesheadere

Brug Add header (Tilføj header) til at definere de headere, der forventes af dit API. Ved et bearer-token skal du bruge headernavnet Authorization, værdikilden Constant og værdien Bearer YOUR_RESTRICTED_TOKEN.

Hold hemmeligheder ude af prompter og URL'er. Undgå handlinger, der returnerer login-tokens til modellen og forlader sig på instruktioner for at skjule dem. Foretræk et integration-slutpunkt på serversiden, der håndterer sin egen godkendelse og kun eksponerer den tilladte handling.

5. Gem og test anmodningen

1. Klik på Save changes (Gem ændringer) i handlingseditoren. I modsætning til normale chatbot-Settings (Indstillinger) har denne editor en eksplicit gem-knap.
2. Klik på Test API Operation (Test API-handling). Den er deaktiveret, så længe der er ugemte ændringer.
3. Indtast repræsentative parameterværdier. Brug kommaseparerede værdier til testinput med arrays.
4. Kør kun testen mod data, du har tilladelse til at læse eller ændre.
5. Undersøg statuskoden, svarbrødteksten, anmodnings-URL'en, headere, brødtekst og eventuelle advarsler vist i resultaterne.
6. Ret fejl, gem, og gentag efter behov.

Del ikke testoutput, der indeholder adgangsoplysninger. Returnér så vidt muligt fokuserede, sideopdelte data: Store svar kan blive afkortet, før de når modellen.

6. Knyt handlingen til en chatbot

Åbn din chatbot, og gå derefter til Settings > Actions (Handlinger). Brug plusknappen til at tilføje en handling, find din handling under tilpassede API'er, og tilknyt eller aktivér den. Oprettelse af en integration på kontoniveau gør ikke automatisk enhver handling tilgængelig for enhver chatbot.

Gennemgå handlingens instruktioner og tilgængelige sikkerhedsindstillinger, og vent derefter på status som gemt. Se AI actions for handlingseditoren.

7. Forklar, hvornår den skal bruges

Åbn Settings > Role & Behavior (Rolle og adfærd).

Hvis du bruger tilpassede rolleinstruktioner, skal du vælge Custom Role Definition (Brugertilpasset rolledefinition) og tilføje en præcis regel, for eksempel: "Når den besøgende spørger, om et produkt er på lager, skal du kalde getProductDetails med dets produkt-ID. Oplys den returnerede tilgængelighed. Hvis opslaget mislykkes, skal du forklare, at tilgængeligheden ikke kunne kontrolleres."

Bevar chatbotten øvrige nyttige instruktioner. Vent på status som gemt, og brug derefter forhåndsvisningen i Overview (Oversigt) til at teste realistiske spørgsmål, manglende parametre, fejl og uautoriserede anmodninger. Samtaler i forhåndsvisningen kan aktivere reelle handlinger.

AI-aktivering er ikke garanteret eller nødvendigvis kun en enkelt gang. Test med den model, der er valgt til din chatbot; gå ikke ud fra, at et modelnavn alene garanterer korrekt brug af værktøjer.

Sikkerhed og fejlfinding

Dit slutpunkt skal godkende anmodninger og autorisere hver enkelt brugers adgang, før det returnerer følsomme oplysninger eller udfører en ændring. Et klient-ID, en e-mailadresse, et ordrenummer eller et kontekstfelt leveret af en browser er ikke tilstrækkeligt bevis på identitet. Hvis du videregiver et brugerspecifikt token via klientkontekst, skal din server validere det.

Returnér kun de felter, chatbotten har brug for, såsom ordrestatus i stedet for en komplet kundeprofil. Prompt-instruktioner kan styre formuleringen, men kan ikke garantere, at følsomme data, der returneres til modellen, forbliver skjult.

Hvis anmodningen lykkes i testeditoren, men ikke i en samtale, skal du kontrollere den tilknyttede handling, dens aktiverede tilstand, instruktioner, påkrævede parametre og tilgængelige kontekst. Hvis begge dele mislykkes, skal du undersøge URL'en, HTTP-metoden, godkendelsen, den genererede brødtekst og dit slutpunkts logfiler. Undgå gentagne forsøg på en skrivehandling, indtil du ved, om den forrige anmodning lykkedes.