Prilagođene API integracije omogućavaju vašem chatbotu da zatraži aktuelne informacije iz vašeg ERP-a, skladišta, CRM-a ili nekog drugog servisa. Takođe mogu da unose izmene, kao što je kreiranje zakazanog termina. Integracija čuva osnovni URL; svaka operacija definiše jedan zahtev koji se može pozvati. Zatim povezujete izabrane operacije sa chatbotom kao AI actions.
Pre nego što počnete
Proverite da li vaš nalog uključuje Custom API integracije. Potrebni su vam URL krajnje tačke (endpoint), HTTP metod, nazivi i tipovi parametara, zahtevi za autentifikaciju i primer odgovora. Krajnja tačka mora biti dostupna sa ChatLab servera; localhost na vašem računaru nije produkciona krajnja tačka.
Koristite HTTPS i test servis ili test zapise za podešavanje. Test zahtev zaista poziva krajnju tačku, pa POST, PATCH ili DELETE mogu promeniti spoljne podatke. Učinite operacije bezbednim za ponavljanje gde god je to moguće.
1. Kreirajte integraciju
- Otvorite Custom Integrations (Prilagođene integracije) u glavnoj navigaciji.
- Kliknite na + Define API Integration (+ Definiši API integraciju).
- Unesite API name (Naziv API-ja) i API Base URL (Osnovni URL API-ja), na primer
https://api.example.com. - Kliknite na Create API Integration (Kreiraj API integraciju).
- U unosu na listi kliknite na View (Pregled), a zatim na + Define API Operation (+ Definiši API operaciju).
2. Definišite operaciju
Dajte operaciji prepoznatljivu oznaku i mašinski čitljiv Operation name (Naziv operacije), kao što je getProductDetails. Za naziv operacije koristite samo slova i brojeve, bez razmaka ili donjih crta. Opišite šta operacija radi i kada chatbot treba da je koristi.
Unesite relativni URI, na primer /v1/products/@productId@. Osnovni URL i URI formiraju adresu zahteva.
Neki postojeći snimci ekrana prikazuju starije primere naziva ili čuvare mesta u vitičastim zagradama. Pratite trenutnu sintaksu prikazanu ispod: nazivi operacija kao što je getProductDetails i čuvari mesta parametara okruženi znakom @.
Parametri putanje i upita
Kliknite na Add path variable (Dodaj promenljivu putanje) da biste definisali productId. Podesite tip podataka i izvor vrednosti, a zatim uključite @productId@ u URI. Promenljive putanje su obavezne, i svaka definisana promenljiva putanje mora se pojaviti u URI-ju pre nego što budete mogli da sačuvate ili testirate.
Koristite Add query parameter (Dodaj parametar upita) za parametre kao što su limit ili language koji idu iza znaka pitanja u URL-u. Unesite naziv koji vaš API očekuje, njegov tip, opis i izvor vrednosti.
Dostupni izvori vrednosti uključuju:
- Provided by user or chatbot (Obezbeđuje korisnik ili chatbot): model obezbeđuje vrednost iz razgovora. Objasnite očekivani format i označite obavezne vrednosti na odgovarajući način.
- Constant (Konstanta): vrednost konfigurisana u operaciji, kao što je fiksni identifikator naloga ili ograničeni API kredencijal.
- Random value (Nasumična vrednost): automatski generisana vrednost.
- Client context (Kontekst klijenta): vrednost koju prosleđuje veb-sajt domaćin, gde je to dostupno za vaš nalog. Pogledajte Chat API.
Skalarni tipovi uključuju string, integer, double i boolean. Parametri tela zahteva takođe podržavaju nizove stringova i celih brojeva.
3. Konfigurišite metod i telo zahteva
Izaberite GET, POST, PUT, PATCH ili DELETE u skladu sa vašom krajnjom tačkom. Za metode koji nisu GET, uređivač nudi raw ili form-data sadržaj zahteva.
Za sirovo JSON telo zahteva, definišite parametre tela i unesite njihove @name@ čuvare mesta u šablon. Dodajte odgovarajuće Content-Type zaglavlje koje vaša krajnja tačka zahteva. Na primer, sa parametrima string name i niz stringova tags:
{
"name": "@name@",
"tags": @tags@
}
Ovo je šablon, a ne doslovni JSON sve dok se ne izvrši zamena. Čuvari mesta za nizove ne smeju biti okruženi navodnicima. Svaki definisani parametar tela mora biti iskorišćen u šablonu kada se primenjuje uređivač sirovog tela zahteva. Proverite generisani zahtev tokom testiranja, uključujući tekst koji sadrži navodnike ili specijalne znakove.
4. Dodajte zaglavlja za autentifikaciju
Koristite Add header (Dodaj zaglavlje) da biste definisali zaglavlja koja API očekuje. Za bearer token koristite naziv zaglavlja Authorization, izvor vrednosti Constant i vrednost Bearer YOUR_RESTRICTED_TOKEN.
Čuvajte tajne podatke van promptova i URL-ova. Izbegavajte operacije koje vraćaju tokene za prijavu modelu i oslanjaju se na instrukcije da ih sakriju. Radije koristite krajnju tačku integracije na strani servera koja upravlja sopstvenom autentifikacijom i izlaže samo dozvoljenu operaciju.
5. Sačuvajte i testirajte zahtev
- Kliknite na Save changes (Sačuvaj izmene) u uređivaču operacije. Za razliku od standardnog menija Settings za chatbot, ovaj uređivač ima eksplicitno dugme za čuvanje.
- Kliknite na Test API Operation (Testiraj API operaciju). Dugme je onemogućeno dok postoje nesačuvane izmene.
- Unesite reprezentativne vrednosti parametara. Za test unose u vidu niza, koristite vrednosti razdvojene zarezom.
- Pokrenite test samo nad podacima za koje imate ovlašćenje da ih čitate ili menjate.
- Pregledajte statusni kod, telo odgovora, URL zahteva, zaglavlja, telo i sva upozorenja prikazana u rezultatima.
- Ispravite greške, sačuvajte i ponovite po potrebi.
Nemojte deliti izlazne podatke testa koji sadrže kredencijale. Vraćajte fokusirane, paginirane podatke gde god je to moguće: veliki odgovori mogu biti skraćeni pre nego što stignu do modela.
6. Povežite operaciju sa chatbotom
Otvorite svoj chatbot, zatim Settings > Actions (Podešavanja > Radnje). Koristite dugme plus da biste dodali radnju, pronađite svoju operaciju pod prilagođenim API-jima i povežite je ili omogućite. Samo kreiranje integracije na nivou naloga ne čini svaku operaciju automatski dostupnom svakom chatbotu.
Pregledajte instrukcije za radnju i dostupna bezbednosna podešavanja, a zatim sačekajte status da je sačuvano. Pogledajte AI actions za uređivač radnji.
7. Objasnite kada treba da se koristi
Otvorite Settings > Role & Behavior (Podešavanja > Uloga i ponašanje).
Ako koristite prilagođene instrukcije za ulogu, izaberite Custom Role Definition (Prilagođena definicija uloge) i dodajte precizno pravilo, na primer: "Kada posetilac pita da li je proizvod na stanju, pozovi getProductDetails sa njegovim ID-jem proizvoda. Prijavi vraćenu dostupnost. Ako pretraga ne uspe, objasni da dostupnost nije mogla da se proveri."
Zadržite ostale korisne instrukcije chatbota. Sačekajte status da je sačuvano, a zatim koristite pregled u Overview (Pregled) da testirate realistična pitanja, nedostajuće parametre, greške i neautorizovane zahteve. Razgovori u pregledu mogu pokrenuti stvarne operacije.
Pokretanje AI-ja nije garantovano niti se nužno dešava samo jednom. Testirajte sa modelom izabranim za vaš chatbot; nemojte pretpostavljati da sam naziv modela garantuje ispravno korišćenje alata.
Bezbednost i rešavanje problema
Vaša krajnja tačka mora autentifikovati zahteve i autorizovati pristup svakog korisnika pre vraćanja osetljivih informacija ili izvršavanja izmene. ID klijenta, email, broj porudžbine ili polje konteksta koje šalje pregledač nisu dovoljan dokaz identiteta. Ako prosleđujete token po korisniku kroz kontekst klijenta, vaš server ga mora validirati.
Vraćajte samo ona polja koja su chatbotu potrebna, kao što je status porudžbine umesto kompletnog profila kupca. Instrukcije u promptu mogu usmeriti formulaciju odgovora, ali ne mogu garantovati da će osetljivi podaci vraćeni modelu ostati skriveni.
Ako zahtev uspe u uređivaču za testiranje, ali ne i u razgovoru, proverite povezanu radnju, da li je omogućena, instrukcije, obavezne parametre i dostupan kontekst. Ako oba ne uspeju, proverite URL, HTTP metod, autentifikaciju, generisano telo i logove vaše krajnje tačke. Izbegavajte uzastopno ponavljanje operacije upisa dok ne saznate da li je prethodni zahtev uspeo.