Integrări API personalizate

Integrați-vă chatbotul cu API-uri personalizate

Folosind editorul nostru de acțiuni AI, puteți construi orice integrare personalizată cu orice sistem backend capabil să expună date prin endpointuri API. De exemplu, puteți face ca chatbotul să verifice disponibilitatea unui produs în depozitul dumneavoastră, să verifice stadiul comenzii în sistemul ERP sau să verifice soldul curent din contul de client.

De asemenea, puteți executa acțiuni pentru a actualiza sisteme externe - de exemplu, puteți apela endpointuri care stabilesc programări sau trimit webhookuri.

Cerințe preliminare

ℹ️ Înainte de a începe - asigurați-vă că dețineți un abonament ChatLab care permite integrări Custom API. Consultați pagina de prețuri

Adăugarea unui Custom API la chatbotul dumneavoastră

Integrarea unui API personalizat îi permite chatbotului dumneavoastră să comunice cu servicii externe - de exemplu magazinul dumneavoastră personalizat -, preluând date sau efectuând acțiuni în numele utilizatorului.

Acest ghid vă va prezenta pașii necesari pentru a configura un API personalizat folosind platforma ChatLab.

API-ul dumneavoastră

Este necesar să aveți endpointuri API disponibile public, care pot fi apelate de către chatbot - acest lucru înseamnă că trebuie să expuneți date din platforma dumneavoastră de e-commerce sau din sistemul dumneavoastră personalizat prin endpointuri API, astfel încât chatbotul nostru să poată apela aceste endpointuri pentru a extrage datele și a le oferi utilizatorilor dumneavoastră.

Apelarea API-ului de către chatbot

API-ul va fi apelat dinamic de către chatbot în timpul interacțiunilor cu utilizatorii, în funcție de necesitatea chatbotului de a accesa date externe sau de a efectua acțiuni specifice. Este important de reținut următoarele aspecte:

• Fără apelare garantată: API-ul va fi apelat doar atunci când logica chatbotului stabilește că este necesar. Nu există garanții cu privire la momentul sau frecvența cu care va fi apelat API-ul.

• Cerințe privind modelele AI: Pentru performanțe optime, se recomandă utilizarea unor modele AI superioare, care acceptă apelarea complexă a funcțiilor (function calling), cum ar fi GPT-4o sau versiuni superioare. Aceste modele sunt mai capabile să determine momentele potrivite pentru a apela API-ul, pe baza contextului conversației și a intenției utilizatorului.

• Apeluri adaptate la context: Chatbotul va încerca să apeleze API-ul ori de câte ori identifică în conversație un context care corespunde scopului API-ului, însă apelul efectiv va depinde de mai mulți factori, cum ar fi:

  • Disponibilitatea și viteza de răspuns a API-ului extern.
  • Starea curentă a conversației și solicitările (prompturile) utilizatorului.
  • Nivelurile interne de încredere și algoritmii de punctare ai modelului AI în evaluarea necesității apelului.

Pași pentru configurarea unui Custom API

Pasul 1: Navigați la setările Custom API

1. Autentificați-vă în panoul de control ChatLab.

2. În bara laterală din stânga, sub secțiunea Settings (Setări), apăsați pe Custom API (API personalizat).

Pasul 2: Definiți un nou API

1. Apăsați pe butonul + Define API (+ Definire API).

2. Introduceți un nume pentru API-ul dumneavoastră în câmpul API Name (Nume API).

3. Introduceți adresa URL de bază a serviciului extern pe care doriți să îl conectați în câmpul URL.

4. Apăsați pe Save (Salvare) pentru a crea API-ul.

Pasul 3: Adăugați operațiuni API

1. În intrarea nou creată pentru API, apăsați pe butonul View (Vizualizare).

2. Apăsați pe + Define API Operation (+ Definire operațiune API) pentru a configura operațiunile individuale (endpointurile) pentru API.

3. Completați detaliile necesare:

• Operation Name (Nume operațiune): Un nume descriptiv pentru operațiune.
• Operation URI (URI operațiune): Calea endpointului pentru operațiune (de exemplu, /v1/resource).

Pasul 4: Configurați URI-ul endpointului și parametrii

1. Configurarea URI-ului de endpoint:

• Adăugați variabilele de cale necesare pentru operațiune apăsând pe + Add path variable (+ Adăugare variabilă de cale).
• Introduceți detaliile variabilei și marcați-le ca obligatorii dacă este necesar.

• Alegeți sursa valorii:
  • Furnizată de utilizator către chatbot - în cazul în care este necesară o valoare de la utilizator pentru a completa acest câmp.
  • Constantă - în cazul în care este o valoare fixă pe care va trebui să o furnizați în momentul definirii operațiunii API
• Adăugați variabila de cale nou introdusă în definiția căii, între două caractere „@”: @myvariable@:

1. Parametri de interogare (Query Parameters):

• Adăugați parametrii de interogare apăsând pe + Add query parameter (+ Adăugare parametru de interogare).
• Definiți numele parametrului, tipul de date și sursa (de exemplu, furnizat de utilizator sau de chatbot).

Pasul 5: Setați metoda de solicitare și corpul cererii (Request Body)

1. Alegeți metoda HTTP pentru operațiune (de exemplu, GET, POST).

2. Dacă metoda solicitării este POST, configurați corpul cererii (request body):

• Alegeți tipul de conținut (de exemplu, application/json).
• Adăugați parametrii pentru body, specificând numele, tipul de date și sursa.

• Adăugați variabilele în definiția body-ului - de regulă, acesta este un format JSON în care puteți plasa variabilele pe care le-ați definit

Pasul 6: Setați anteturile (headers) operațiunii

Adăugați anteturi - de exemplu, Authorization sau altele necesare API-ului dumneavoastră. Vă rugăm să consultați captura de ecran de mai jos pentru configurarea unui token permanent în antetul Authorization:

Pasul 7: Salvați operațiunea

1. Verificați configurația pentru a vă asigura că toate detaliile sunt corecte.

2. Apăsați pe Save changes (Salvare modificări) pentru a salva operațiunea API.

Pasul 8: Testați integrarea API

1. Utilizați funcția Test API (Testare API) pentru a trimite o solicitare de test și a vă asigura că integrarea funcționează corect.

2. Monitorizați jurnalele (logs) pentru eventuale erori sau probleme și ajustați configurația după cum este necesar.

Pasul 9: Asociați operațiunile API la chatbot

După ce ați definit operațiunile API, este momentul să le atribuiți chatbotului. Selectați chatbotul în panoul principal de control, apăsați pe Integrations (Integrări) și selectați AI API Actions (Acțiuni API AI) din meniul din stânga

Apăsați pe Attach (Atașare) la operațiunea API selectată

Pasul 10: Adăugați instrucțiuni de rol pentru chatbot

Selectați chatbotul dumneavoastră în panoul principal de control, apăsați pe Settings (Setări), iar în meniul din stânga selectați Role (Rol)

Apăsați pe Provide custom role instructions (Furnizare instrucțiuni personalizate de rol).

Adăugați instrucțiuni privind utilizarea operațiunii API nou adăugate; de exemplu, puteți adăuga o regulă:

„- Când utilizatorul întreabă despre stocul magazinului, apelează întotdeauna funcția getItems și afișează rezultatul funcției conform următoarelor reguli…..”

Sfaturi pentru o integrare reușită

• Asigurați-vă că adresa URL de bază și endpointurile sunt corecte și accesibile.

• Verificați dacă toate cerințele de autentificare (cum ar fi cheile API sau tokenurile) sunt configurate corespunzător.

• Testați fiecare operațiune în detaliu pentru a vă asigura că returnează răspunsurile așteptate.

Urmând acești pași, puteți integra fără probleme API-uri personalizate în chatbotul dumneavoastră ChatLab, extinzându-i funcționalitatea și oferind o experiență mai bogată utilizatorilor.

Securizarea integrării Custom API

Pentru a vă asigura că API-ul dumneavoastră personalizat este sigur și protejat împotriva accesului neautorizat, luați în considerare următoarele bune practici:

Utilizați tokenuri constante

Tokenuri API constante: Configurați un token API constant (sau o cheie) care să fie obligatoriu pentru toate solicitările către API. Acest token trebuie să fie unic și generat în mod securizat.

• Cum se implementează: Includeți tokenul în antetul solicitării (request header) sau ca parametru de interogare (query parameter) în fiecare apel API.

• Unde se stochează: Stocați tokenul în siguranță în setările ChatLab, ca parametru constant al operațiunii

Utilizați un endpoint de autentificare pentru tokenuri temporare

Adăugați o operațiune API suplimentară la nivelul API-ului, care returnează un token de securitate temporar - adică un endpoint de autentificare (login) în sistemul dumneavoastră.

Va trebui să introduceți datele de autentificare corespunzătoare sistemului dumneavoastră ca parametri constanți ai operațiunii API atunci când o definiți. Pentru ca chatbotul să poată utiliza tokenul obținut în acest mod, trebuie să adăugați tokenul de securitate în definițiile celorlalte operațiuni API și să introduceți instrucțiuni corespunzătoare de prompt atât pentru operațiunea de autentificare, cât și pentru celelalte operațiuni API (de exemplu: „Utilizează întotdeauna tokenul de securitate obținut din operațiunea Login ca parametru security_token pentru operațiunea getOrder”).

Controlul informațiilor sensibile prin ChatLab

Pentru a preveni afișarea informațiilor sensibile de către chatbot, utilizatorii ChatLab pot lua următoarele măsuri:

Utilizați formularea strategică a prompturilor (prompt engineering) pentru a ghida comportamentul AI

• Stabiliți instrucțiuni clare în prompturi: Când configurați chatbotul, oferiți instrucțiuni explicite în setările promptului pentru a evita afișarea oricăror informații sensibile. De exemplu:

  • Exemplu de prompt: „Nu afișa informații personale, financiare sau confidențiale returnate de un apel API.”
  • Utilizarea mesajelor de sistem: Includeți un mesaj de sistem la începutul fluxului conversațional pentru a consolida importanța confidențialității datelor (de exemplu: „Asigură-te că toate răspunsurile exclud orice informație sensibilă.”).

• Actualizați periodic prompturile: Ajustați prompturile pe baza feedbackului primit de la utilizatori sau a modificărilor cerințelor de confidențialitate a datelor. Acest lucru garantează că AI-ul respectă consecvent cele mai recente orientări privind gestionarea informațiilor sensibile.

Proiectați endpointurile API cu logică de verificare integrată

• Solicitați verificarea utilizatorului pentru accesul la date sensibile: Proiectați endpointurile API astfel încât să includă verificări înainte de a returna date sensibile. De exemplu:

  • Parametri de verificare: Solicitați utilizatorilor să furnizeze anumite informații (cum ar fi o adresă de e-mail, un număr de comandă sau o întrebare specifică de securitate) înainte ca API-ul să returneze date asociate acelui utilizator.
  • Verificare cu factori multipli: Implementați parametri suplimentari (de exemplu: data comenzii, adresa de livrare sau un cod secret) pentru a verifica identitatea utilizatorului și a vă asigura că acesta este autorizat să acceseze datele.

• Implementați răspunsuri de siguranță (fail-safe): Configurați logica API-ului să returneze mesaje generice sau erori dacă datele de verificare necesare nu sunt furnizate sau nu coincid:

  • Exemplu: „Detaliile comenzii nu au putut fi preluate. Vă rugăm să vă verificați adresa de e-mail și numărul comenzii.”

Utilizați domenii limitate de date în răspunsurile API

• Minimizați expunerea datelor: Configurați răspunsurile API astfel încât să includă doar datele strict necesare pentru funcționarea chatbotului, reducând riscul de a afișa accidental informații sensibile.
  • Exemplu: În loc să returnați profilul complet al utilizatorului, returnați doar câmpuri specifice, cum ar fi stadiul comenzii sau confirmarea plății, care sunt necesare pentru sarcina curentă a chatbotului.