Integrările Custom API permit chatbotului dumneavoastră să solicite informații în timp real din sistemul dumneavoastră ERP, din depozit, CRM sau dintr-un alt serviciu. De asemenea, acestea pot efectua modificări, cum ar fi crearea unei programări. O integrare stochează adresa URL de bază; fiecare operațiune definește o solicitare apelabilă. Apoi atașați operațiunile selectate la un chatbot sub formă de acțiuni AI.
Înainte de a începe
Verificați dacă contul dumneavoastră include integrări Custom API. Aveți nevoie de adresa URL a endpointului, metoda HTTP, numele și tipurile parametrilor, cerințele de autentificare și un exemplu de răspuns. Endpointul trebuie să fie accesibil de pe serverele ChatLab; localhost de pe computerul dumneavoastră nu este un endpoint de producție.
Utilizați HTTPS și un serviciu de testare sau înregistrări de testare pentru configurare. O solicitare de testare apelează efectiv endpointul, astfel încât o metodă POST, PATCH sau DELETE poate modifica date externe. Faceți ca operațiunile să poată fi repetate în siguranță acolo unde este posibil.
1. Creați o integrare
- Deschideți Custom Integrations (Integrări personalizate) în navigarea principală.
- Faceți clic pe + Define API Integration (+ Definiți integrarea API).
- Introduceți API name (Nume API) și API Base URL (Adresă URL de bază API), de exemplu
https://api.example.com. - Faceți clic pe Create API Integration (Creați integrarea API).
- În intrarea corespunzătoare din listă, faceți clic pe View (Vizualizare), apoi pe + Define API Operation (+ Definiți operațiunea API).
2. Definiți operațiunea
Atribuiți operațiunii o etichetă ușor de recunoscut și un Operation name (Nume operațiune) care poate fi citit automat, cum ar fi getProductDetails. Utilizați doar litere și cifre pentru numele operațiunii, fără spații sau caractere de subliniere. Descrieți ce face operațiunea și când ar trebui să o utilizeze chatbotul.
Introduceți URI-ul relativ, de exemplu /v1/products/@productId@. Adresa URL de bază și URI-ul formează adresa solicitării.
Unele capturi de ecran existente prezintă denumiri demonstrative mai vechi sau substituenți de tip acolade. Respectați sintaxa actuală de mai jos: nume de operațiuni precum getProductDetails și substituenți de parametri încadrați de @.
Parametri de cale și de interogare
Faceți clic pe Add path variable (Adăugați variabilă de cale) pentru a defini productId. Setați tipul său de date și sursa valorii, apoi includeți @productId@ în URI. Variabilele de cale sunt obligatorii, iar fiecare variabilă de cale definită trebuie să apară în URI înainte de a putea salva sau testa.
Utilizați Add query parameter (Adăugați parametru de interogare) pentru parametri precum limit sau language, care se plasează după semnul întrebării din adresa URL. Introduceți numele așteptat de API-ul dumneavoastră, tipul acestuia, descrierea și sursa valorii.
Sursele de valoare disponibile includ:
- Provided by user or chatbot: modelul furnizează o valoare din conversație. Explicați formatul așteptat și marcați valorile obligatorii în mod corespunzător.
- Constant: o valoare configurată în cadrul operațiunii, cum ar fi un identificator de cont fix sau o credențială API restricționată.
- Random value: o valoare generată automat.
- Client context: o valoare transmisă de site-ul gazdă, acolo unde este disponibilă pentru contul dumneavoastră. Consultați Chat API.
Tipurile scalare includ string, integer, double și boolean. Parametrii de corp acceptă, de asemenea, matrice de tip string și integer.
3. Configurați metoda și corpul solicitării
Alegeți GET, POST, PUT, PATCH sau DELETE pentru a corespunde endpointului dumneavoastră. Pentru alte metode decât GET, editorul pune la dispoziție conținut de solicitare de tip raw sau form-data.
Pentru un corp JSON brut (raw), definiți parametrii corpului și introduceți substituenții acestora de tip @name@ în șablon. Adăugați antetul Content-Type corespunzător, cerut de endpointul dumneavoastră. De exemplu, cu parametrii name de tip string și tags de tip matrice de șiruri:
{
"name": "@name@",
"tags": @tags@
}
Acesta este un șablon, nu un JSON propriu-zis până la substituție. Substituenții de tip matrice nu trebuie încadrați între ghilimele. Fiecare parametru de corp definit trebuie utilizat în șablon atunci când se aplică editorul de corp brut. Verificați solicitarea randată în timpul testării, inclusiv textele care conțin ghilimele sau caractere speciale.
4. Adăugați antete de autentificare
Utilizați Add header (Adăugați antet) pentru a defini antetele așteptate de API. Pentru un token bearer, utilizați numele de antet Authorization, sursa de valoare Constant și valoarea Bearer YOUR_RESTRICTED_TOKEN.
Păstrați datele confidențiale în afara prompturilor și a adreselor URL. Evitați operațiunile care returnează tokenuri de conectare către model și care se bazează pe instrucțiuni pentru a le ascunde. Preferați un endpoint de integrare pe partea de server care își gestionează propria autentificare și expune doar operațiunea permisă.
5. Salvați și testați solicitarea
- Faceți clic pe Save changes (Salvați modificările) în editorul de operațiuni. Spre deosebire de secțiunea obișnuită Settings (Setări) a chatbotului, acest editor are un buton explicit de salvare.
- Faceți clic pe Test API Operation (Testați operațiunea API). Acesta este dezactivat atât timp cât modificările nu sunt salvate.
- Introduceți valori reprezentative pentru parametri. Pentru valorile de testare de tip matrice, utilizați valori separate prin virgulă.
- Rulați testul numai asupra datelor pe care sunteți autorizat să le citiți sau să le modificați.
- Inspectați codul de stare, corpul răspunsului, adresa URL a solicitării, antetele, corpul și orice avertisment afișat în rezultate.
- Corectați erorile, salvați și repetați după cum este necesar.
Nu partajați date de ieșire din teste care conțin credențiale. Returnați date concentrate, paginate, acolo unde este posibil: răspunsurile de mari dimensiuni pot fi trunchiate înainte de a ajunge la model.
6. Atașați operațiunea la un chatbot
Deschideți chatbotul dumneavoastră, apoi accesați Settings > Actions (Setări > Acțiuni). Utilizați butonul plus pentru a adăuga o acțiune, găsiți operațiunea dumneavoastră la categoria integrărilor API personalizate și atașați-o sau activați-o. Crearea unei integrări la nivel de cont nu face în mod automat fiecare operațiune disponibilă pentru fiecare chatbot.
Examinați instrucțiunile acțiunii și setările de securitate disponibile, apoi așteptați confirmarea salvării. Consultați acțiuni AI pentru detalii despre editorul de acțiuni.
7. Explicați când trebuie utilizată
Deschideți Settings > Role & Behavior (Setări > Rol și comportament).
Dacă utilizați instrucțiuni de rol personalizate, selectați Custom Role Definition (Definiție personalizată a rolului) și adăugați o regulă precisă, de exemplu: "Atunci când vizitatorul întreabă dacă un produs este în stoc, apelează getProductDetails cu ID-ul produsului respectiv. Comunică disponibilitatea returnată. Dacă verificarea eșuează, explică faptul că disponibilitatea nu a putut fi verificată."
Păstrați celelalte instrucțiuni utile ale chatbotului. Așteptați confirmarea salvării, apoi utilizați previzualizarea din secțiunea Overview (Prezentare generală) pentru a testa întrebări realiste, parametri lipsă, erori și solicitări neautorizate. Conversațiile din modul de previzualizare pot invoca operațiuni reale.
Apelarea de către AI nu este garantată și nici nu are loc neapărat o singură dată. Testați comportamentul cu modelul selectat pentru chatbotul dumneavoastră; nu presupuneți că denumirea modelului garantează de la sine utilizarea corectă a instrumentelor.
Securitate și depanare
Endpointul dumneavoastră trebuie să autentifice solicitările și să autorizeze accesul fiecărui utilizator înainte de a returna informații sensibile sau de a efectua o modificare. Un identificator de client furnizat de browser, o adresă de e-mail, un număr de comandă sau un câmp de context nu reprezintă o dovadă suficientă a identității. Dacă transmiteți un token specific utilizatorului prin intermediul contextului de client, serverul dumneavoastră trebuie să îl valideze.
Returnați doar câmpurile de care are nevoie chatbotul, cum ar fi starea comenzii în locul unui profil complet de client. Instrucțiunile din prompt pot ghida formularea răspunsurilor, dar nu pot garanta că datele sensibile returnate către model rămân ascunse.
Dacă solicitarea reușește în editorul de testare, dar nu și într-o conversație, verificați acțiunea atașată, starea activată a acesteia, instrucțiunile, parametrii obligatorii și contextul disponibil. Dacă ambele eșuează, inspectați adresa URL, metoda HTTP, autentificarea, corpul randat și jurnalele endpointului dumneavoastră. Evitați să reîncercați în mod repetat o operațiune de scriere înainte de a ști dacă solicitarea anterioară a reușit.