Anpassade API-integrationer låter din chattbot hämta aktuell information i realtid från ditt affärssystem, lager, CRM eller en annan tjänst. De kan även utföra ändringar, till exempel boka ett möte. En integration lagrar bas-URL:en; varje operation definierar en anropsbar förfrågan. Därefter kopplar du valda operationer till en chattbot som AI-åtgärder.
Innan du börjar
Kontrollera att ditt konto inkluderar anpassade API-integrationer. Du behöver slutpunktens URL, HTTP-metod, parameternamn och parametertyper, autentiseringskrav samt ett exempelsvar. Slutpunkten måste vara nåbar från ChatLabs servrar; localhost på din dator är ingen produktionsslutpunkt.
Använd HTTPS och en testtjänst eller testposter under konfigurationen. En testförfrågan anropar slutpunkten på riktigt, så en POST, PATCH eller DELETE kan ändra externa data. Gör operationerna säkra att upprepa där det är möjligt.
1. Skapa en integration
- Öppna Custom Integrations (Anpassade integrationer) i huvudnavigeringen.
- Klicka på + Define API Integration (+ Definiera API-integration).
- Ange API name (API-namn) och API Base URL (API-bas-URL), till exempel
https://api.example.com. - Klicka på Create API Integration (Skapa API-integration).
- Klicka på View (Visa) i dess listpost, och sedan på + Define API Operation (+ Definiera API-operation).
2. Definiera operationen
Ge operationen en igenkännbar etikett och ett maskinläsbart Operation name (Operationsnamn), till exempel getProductDetails. Använd endast bokstäver och siffror för operationsnamnet, inte mellanslag eller understreck. Beskriv vad operationen gör och när chattbotten ska använda den.
Ange den relativa URI:n, till exempel /v1/products/@productId@. Bas-URL:en och URI:n bildar tillsammans förfrågningsadressen.
Vissa befintliga skärmbilder visar äldre exempelnamn eller platshållare med klammerparenteser. Följ den aktuella syntaxen nedan: operationsnamn som getProductDetails och parameterplatshållare omgivna av @.
Sökvägs- och frågeparametrar
Klicka på Add path variable (Lägg till sökvägsvariabel) för att definiera productId. Ange dess datatyp och värdekälla, och inkludera sedan @productId@ i URI:n. Sökvägsvariabler är obligatoriska, och varje definierad sökvägsvariabel måste finnas med i URI:n innan du kan spara eller testa.
Använd Add query parameter (Lägg till frågeparameter) för parametrar som limit eller language som hör hemma efter URL:ens frågetecken. Ange namnet som förväntas av ditt API, dess typ, beskrivning och värdekälla.
Tillgängliga värdekällor inkluderar:
- Provided by user or chatbot: modellen tillhandahåller ett värde från konversationen. Förklara det förväntade formatet och markera obligatoriska värden på lämpligt sätt.
- Constant: ett värde som konfigurerats i operationen, såsom en fast kontoidentifierare eller en begränsad API-uppgift.
- Random value: ett värde som genereras automatiskt.
- Client context: ett värde som skickas från värdwebbplatsen, där det är tillgängligt för ditt konto. Se Chat API.
Skalära typer inkluderar sträng (string), heltal (integer), flyttal (double) och booleskt värde (boolean). Body-parametrar stöder även sträng- och heltalsmatriser.
3. Konfigurera metod och body
Välj GET, POST, PUT, PATCH eller DELETE för att matcha din slutpunkt. För andra metoder än GET erbjuder redigeraren raw- eller form-data-innehåll för förfrågan.
För en JSON-body i råformat (raw) definierar du parametrarna för bodyn och infogar deras @name@-platshållare i mallen. Lägg till lämpligt Content-Type-headerfält som krävs av din slutpunkt. Till exempel, med strängparametern name och strängmatrisparametern tags:
{
"name": "@name@",
"tags": @tags@
}
Detta är en mall, inte bokstavlig JSON förrän ersättningen har skett. Platshållare för matriser får inte omges av citattecken. Varje definierad body-parameter måste användas i mallen när raw body-redigeraren används. Kontrollera den genererade förfrågan under testningen, inklusive text som innehåller citattecken eller specialtecken.
4. Lägg till autentiseringsheaders
Använd Add header (Lägg till header) för att definiera de headers som förväntas av API:et. För en bearer-token använder du headernamnet Authorization, värdekällan Constant och värdet Bearer YOUR_RESTRICTED_TOKEN.
Håll hemligheter borta från promptar och URL:er. Undvik operationer som returnerar inloggningstokens till modellen och förlitar sig på instruktioner för att dölja dem. Föredra en integrationsslutpunkt på serversidan som hanterar sin egen autentisering och endast exponerar den tillåtna operationen.
5. Spara och testa förfrågan
- Klicka på Save changes (Spara ändringar) i operationsredigeraren. Till skillnad från vanliga chattbot-Settings (Inställningar) har denna redigerare en explicit sparaknapp.
- Klicka på Test API Operation (Testa API-operation). Den är inaktiverad så länge det finns osparade ändringar.
- Ange representativa parametervärden. För testinmatning av matriser använder du kommaseparerade värden.
- Kör endast testet mot data som du har behörighet att läsa eller ändra.
- Granska statuskod, svars-body, anrops-URL, headers, body och eventuella varningar som visas i resultatet.
- Åtgärda fel, spara och upprepa vid behov.
Dela inte testutdata som innehåller inloggningsuppgifter. Returnera fokuserade, paginerade data där det är möjligt: stora svar kan trunkeras innan de når modellen.
6. Koppla operationen till en chattbot
Öppna din chattbot, gå sedan till Settings > Actions (Inställningar > Åtgärder). Använd plusknappen för att lägga till en åtgärd, leta upp din operation under anpassade API:er och koppla eller aktivera den. Att enbart skapa en integration på kontonivå gör inte varje operation tillgänglig för varje chattbot.
Granska åtgärdens instruktioner och tillgängliga säkerhetsinställningar, och vänta sedan på statusen att den sparats. Se AI-åtgärder för åtgärdsredigeraren.
7. Förklara när den ska användas
Öppna Settings > Role & Behavior (Inställningar > Roll och beteende).
Om du använder anpassade rollinstruktioner väljer du Custom Role Definition (Anpassad rolldefinition) och lägger till en precis regel, till exempel: "När besökaren frågar om en produkt finns i lager, anropa getProductDetails med dess produkt-ID. Återge tillgängligheten som returneras. Om sökningen misslyckas, förklara att det inte gick att kontrollera tillgängligheten."
Behåll chattbottens övriga användbara instruktioner. Vänta på statusen att ändringarna sparats och använd sedan förhandsgranskningen i Overview (Översikt) för att testa realistiska frågor, saknade parametrar, fel och obehöriga förfrågningar. Förhandsgranskningskonversationer kan utföra verkliga operationer.
AI-anrop är inte garanterade eller nödvändigtvis begränsade till en enda gång. Testa med den modell som valts för din chattbot; anta inte att ett modellnamn ensamt garanterar korrekt verktygsanvändning.
Säkerhet och felsökning
Din slutpunkt måste autentisera förfrågningar och auktorisera varje användares åtkomst innan känslig information returneras eller en ändring utförs. Ett klient-ID, en e-postadress, ett ordernummer eller ett kontextfält som tillhandahålls av webbläsaren är inte tillräckligt som identitetsbevis. Om du skickar en token per användare via klientkontext måste din server validera den.
Returnera endast de fält som chattbotten behöver, till exempel orderstatus istället för en fullständig kundprofil. Promptinstruktioner kan styra formuleringar, men kan inte garantera att känsliga data som returneras till modellen förblir dolda.
Om förfrågan lyckas i testredigeraren men inte i en konversation kontrollerar du den kopplade åtgärden, dess aktiverade status, instruktioner, obligatoriska parametrar och tillgänglig kontext. Om båda misslyckas undersöker du URL, HTTP-metod, autentisering, den genererade bodyn och loggarna för din slutpunkt. Undvik att upprepade gånger försöka göra om en skrivoperation innan du vet om den föregående förfrågan lyckades.