Własne integracje API pozwalają Twojemu chatbotowi pobierać aktualne informacje z Twojego systemu ERP, magazynu, CRM lub innej usługi. Mogą też wprowadzać zmiany, na przykład tworzyć rezerwację. Integracja przechowuje bazowy adres URL, a każda operacja definiuje jedno wywołanie. Następnie przypisujesz wybrane operacje do chatbota jako akcje AI (AI actions).
Zanim zaczniesz
Sprawdź, czy Twoje konto ma dostęp do własnych integracji API (Custom API integrations). Potrzebujesz adresu URL endpointu, metody HTTP, nazw i typów parametrów, wymagań dotyczących uwierzytelniania oraz przykładowej odpowiedzi. Endpoint musi być dostępny z serwerów ChatLab; localhost na Twoim komputerze nie jest endpointem produkcyjnym.
Do konfiguracji używaj protokołu HTTPS oraz usługi testowej lub rekordów testowych. Żądanie testowe rzeczywiście wywołuje endpoint, więc metoda POST, PATCH lub DELETE może zmodyfikować dane zewnętrzne. W miarę możliwości zadbaj o to, aby operacje były bezpieczne do powtórzenia.
1. Utwórz integrację
- Otwórz Własne integracje (Custom Integrations) w menu głównym.
- Kliknij + Zdefiniuj integrację API (+ Define API Integration).
- Wpisz Nazwa API (API name) oraz Bazowy adres URL API (API Base URL), na przykład
https://api.example.com. - Kliknij Utwórz integrację API (Create API Integration).
- Na liście kliknij Wyświetl (View) przy danej integracji, a następnie + Zdefiniuj operację API (+ Define API Operation).
2. Zdefiniuj operację
Nadaj operacji czytelną etykietę oraz zrozumiałą dla maszyny nazwę (Operation name), na przykład getProductDetails. W nazwie operacji używaj wyłącznie liter i cyfr - bez spacji ani podkreśleń. Opisz, co robi ta operacja i kiedy chatbot powinien z niej korzystać.
Wpisz względny identyfikator URI, na przykład /v1/products/@productId@. Bazowy URL i URI tworzą razem pełny adres żądania.
Niektóre z dotychczasowych zrzutów ekranu przedstawiają starsze przykładowe nazwy lub symbole zastępcze w nawiasach klamrowych. Zastosuj poniższą aktualną składnię: nazwy operacji takie jak getProductDetails oraz symbole zastępcze parametrów otoczone znakami @.
Parametry ścieżki i zapytania
Kliknij Add path variable (Dodaj zmienną ścieżki), aby zdefiniować productId. Ustaw jej typ danych oraz źródło wartości, a następnie umieść @productId@ w URI. Zmienne ścieżki są wymagane, a każda zdefiniowana zmienna ścieżki musi pojawić się w URI, zanim będzie można zapisać lub przetestować konfigurację.
Użyj przycisku Add query parameter (Dodaj parametr zapytania) dla parametrów takich jak limit lub language, które znajdują się po znaku zapytania w adresie URL. Wprowadź nazwę oczekiwaną przez Twoje API, jej typ, opis oraz źródło wartości.
Dostępne źródła wartości obejmują:
- Provided by user or chatbot (Dostarczone przez użytkownika lub chatbota): model pobiera wartość z rozmowy. Wyjaśnij oczekiwany format i odpowiednio oznacz wymagane wartości.
- Constant (Stała): wartość skonfigurowana w operacji, na przykład stały identyfikator konta lub dane uwierzytelniające API o ograniczonych uprawnieniach.
- Random value (Wartość losowa): wartość generowana automatycznie.
- Client context (Kontekst klienta): wartość przekazywana przez stronę, na której osadzony jest chatbot, jeśli funkcja jest dostępna dla Twojego konta. Zobacz Chat API.
Typy skalarne obejmują string (ciąg znaków), integer (liczba całkowita), double (liczba zmiennoprzecinkowa) i boolean (wartość logiczna). Parametry treści (body) obsługują także tablice ciągów znaków (string) i liczb całkowitych (integer).
3. Skonfiguruj metodę i treść żądania (Method i Body)
Wybierz GET, POST, PUT, PATCH lub DELETE, aby dopasować metodę do Twojego punktu końcowego (endpointu). W przypadku metod innych niż GET edytor oferuje zawartość żądania w formacie raw lub form-data.
W przypadku treści raw JSON zdefiniuj parametry treści (body parameters) i wstaw ich placeholdery @name@ w szablonie. Dodaj odpowiedni nagłówek Content-Type wymagany przez Twój endpoint. Na przykład dla parametrów tekstowych name oraz tablicy ciągów znaków tags:
{
"name": "@name@",
"tags": @tags@
}
Jest to szablon, a nie dosłowny JSON aż do momentu podstawienia wartości. Placeholdery tablic nie mogą być ujęte w cudzysłowy. Każdy zdefiniowany parametr treści musi zostać użyty w szablonie, gdy aktywny jest edytor treści raw. Sprawdź wygenerowane żądanie podczas testów, w tym tekst zawierający cudzysłowy lub znaki specjalne.
4. Dodaj nagłówki uwierzytelniania
Użyj opcji Add header (Dodaj nagłówek), aby zdefiniować nagłówki oczekiwane przez API. W przypadku tokena bearer użyj nazwy nagłówka Authorization, źródła wartości Constant (Stała) oraz wartości Bearer YOUR_RESTRICTED_TOKEN.
Nie umieszczaj danych poufnych w promptach ani adresach URL. Unikaj operacji, które zwracają tokeny logowania do modelu i polegają na instrukcjach w celu ich ukrycia. Lepiej korzystać z punktu końcowego integracji po stronie serwera, który samodzielnie zarządza własnym uwierzytelnianiem i udostępnia wyłącznie dozwoloną operację.
5. Zapisz i przetestuj żądanie
- Kliknij Save changes (Zapisz zmiany) w edytorze operacji. W przeciwieństwie do standardowych ustawień chatbota (Settings), ten edytor zawiera dedykowany przycisk zapisu.
- Kliknij Test API Operation (Przetestuj operację API). Przycisk jest nieaktywny, dopóki zmiany nie zostaną zapisane.
- Wprowadź reprezentatywne wartości parametrów. W przypadku testowych danych tablicowych użyj wartości rozdzielonych przecinkami.
- Uruchamiaj test wyłącznie na danych, do których odczytu lub modyfikacji masz uprawnienia.
- Sprawdź kod statusu, treść odpowiedzi (response body), URL żądania, nagłówki, treść żądania (body) oraz wszelkie ostrzeżenia widoczne w wynikach.
- Popraw błędy, zapisz zmiany i powtórz w razie potrzeby.
Nie udostępniaj wyników testów zawierających dane uwierzytelniające. W miarę możliwości zwracaj precyzyjne, stronicowane dane: zbyt duże odpowiedzi mogą zostać obcięte, zanim trafią do modelu.
6. Przypisz operację do chatbota
Otwórz swojego chatbota, a następnie przejdź do Settings > Actions (Ustawienia > Akcje). Użyj przycisku z plusem, aby dodać akcję, znajdź swoją operację w sekcji niestandardowych API i przypisz ją lub włącz. Samo utworzenie integracji na poziomie konta nie sprawia, że każda operacja staje się dostępna dla każdego chatbota.
Przejrzyj instrukcje akcji oraz dostępne ustawienia bezpieczeństwa, a następnie poczekaj na potwierdzenie zapisu. Zobacz Akcje AI, aby dowiedzieć się więcej o edytorze akcji.
7. Wyjaśnij, kiedy z tego korzystać
Przejdź do Ustawienia > Rola i zachowanie (Settings > Role & Behavior).
Jeśli używasz własnych instrukcji roli, wybierz Niestandardowa definicja roli (Custom Role Definition) i dodaj precyzyjną regułę, na przykład: "Gdy użytkownik pyta, czy produkt jest dostępny, wywołaj getProductDetails z jego identyfikatorem produktu. Przekaż zwróconą dostępność. Jeśli wyszukiwanie się nie powiedzie, wyjaśnij, że nie udało się sprawdzić dostępności."
Zachowaj pozostałe przydatne instrukcje chatbota. Poczekaj na potwierdzenie zapisania, a następnie użyj podglądu w zakładce Przegląd (Overview), aby przetestować realistyczne pytania, brakujące parametry, błędy oraz nieautoryzowane zapytania. Rozmowy w podglądzie mogą wywoływać rzeczywiste operacje.
Wywołanie przez AI nie jest gwarantowane ani nie musi nastąpić tylko raz. Testuj z modelem wybranym dla Twojego chatbota; nie zakładaj, że sama nazwa modelu gwarantuje poprawne użycie narzędzi.
Bezpieczeństwo i rozwiązywanie problemów
Twój endpoint musi uwierzytelniać żądania i autoryzować dostęp każdego użytkownika przed zwróceniem poufnych informacji lub wprowadzeniem zmian. Identyfikator klienta, adres e-mail, numer zamówienia czy pole kontekstu przekazane przez przeglądarkę nie stanowią wystarczającego dowodu tożsamości. Jeśli przekazujesz token użytkownika przez kontekst klienta, Twój serwer musi go zweryfikować.
Zwracaj tylko te pola, których chatbot rzeczywiście potrzebuje - na przykład status zamówienia zamiast pełnego profilu klienta. Instrukcje w prompcie mogą pokierować sposobem formułowania odpowiedzi, ale nie gwarantują, że poufne dane przekazane do modelu pozostaną ukryte.
Jeśli żądanie kończy się powodzeniem w edytorze testowym, ale nie działa w rozmowie, sprawdź podpiętą akcję, jej stan włączenia, instrukcje, wymagane parametry oraz dostępny kontekst. Jeśli oba sposoby zawodzą, zweryfikuj adres URL, metodę HTTP, uwierzytelnianie, wygenerowaną treść żądania (body) oraz logi swojego endpointa. Unikaj wielokrotnego ponawiania operacji zapisu, dopóki nie upewnisz się, czy poprzednie żądanie zakończyło się sukcesem.