Vlastní integrace API umožňují vašemu chatbotu vyžadovat aktuální informace z vašeho ERP, skladu, CRM nebo jiné služby. Mohou také provádět změny, například vytvořit schůzku. Integrace ukládá základní URL; každá operace definuje jeden volatelný požadavek. Vybrané operace pak k chatbotu připojíte jako akce AI (AI actions).
Než začnete
Zkontrolujte, zda váš účet zahrnuje Custom API integrations (vlastní integrace API). Budete potřebovat URL koncového bodu (endpointu), metodu HTTP, názvy a typy parametrů, požadavky na ověření a ukázkovou odpověď. Koncový bod musí být dostupný ze serverů ChatLab; localhost na vašem počítači není produkční koncový bod.
Pro nastavení používejte HTTPS a testovací službu nebo testovací záznamy. Testovací požadavek koncový bod skutečně zavolá, takže POST, PATCH nebo DELETE mohou změnit externí data. Kde je to možné, zajistěte, aby byly operace bezpečně opakovatelné.
1. Vytvoření integrace
- V hlavní navigaci otevřete Custom Integrations (Vlastní integrace).
- Klikněte na + Define API Integration (+ Definovat integraci API).
- Zadejte API name (Název API) a API Base URL (Základní URL rozhraní API), například
https://api.example.com. - Klikněte na Create API Integration (Vytvořit integraci API).
- V jejím záznamu v seznamu klikněte na View (Zobrazit) a poté na + Define API Operation (+ Definovat operaci API).
2. Definujte operaci
Pojmenujte operaci srozumitelným štítkem a zadejte strojově čitelný Název operace (Operation name), například getProductDetails. V názvu operace používejte pouze písmena a čísla, nikoli mezery nebo podtržítka. Popište, co operace dělá a kdy by ji měl chatbot použít.
Zadejte relativní URI, například /v1/products/@productId@. Základní URL a URI tvoří adresu požadavku.
Některé stávající snímky obrazovky zobrazují starší ukázkové názvy nebo zástupné symboly se složenými závorkami. Řiďte se níže uvedenou aktuální syntaxí: názvy operací jako getProductDetails a zástupné symboly parametrů ohraničené @.
Parametry cesty a dotazu
Kliknutím na Přidat proměnnou cesty (Add path variable) definujte productId. Nastavte její datový typ a zdroj hodnoty a poté vložte @productId@ do URI. Proměnné cesty jsou povinné a každá definovaná proměnná cesty se musí objevit v URI, než budete moci operaci uložit nebo otestovat.
Pomocí Přidat parametr dotazu (Add query parameter) přidejte parametry jako limit nebo language, které patří za otazník v URL. Zadejte název očekávaný vaším API, jeho typ, popis a zdroj hodnoty.
Mezi dostupné zdroje hodnot patří:
- Provided by user or chatbot (Poskytnuto uživatelem nebo chatbotem): model dodá hodnotu z konverzace. Vysvětlete očekávaný formát a řádně označte povinné hodnoty.
- Constant (Konstanta): hodnota nakonfigurovaná přímo v operaci, například pevný identifikátor účtu nebo omezený přihlašovací údaj k API.
- Random value (Náhodná hodnota): automaticky vygenerovaná hodnota.
- Client context (Kontext klienta): hodnota předaná hostitelským webem, pokud je pro váš účet k dispozici. Viz Chat API.
Mezi skalární typy patří string, integer, double a boolean. Parametry těla (body) podporují také pole řetězců (string) a celých čísel (integer).
3. Nakonfigurujte metodu a tělo požadavku (Method and Body)
Zvolte GET, POST, PUT, PATCH nebo DELETE podle svého koncového bodu. U jiných metod než GET nabízí editor obsah požadavku jako raw (nezpracovaný) nebo form-data.
Pro tělo požadavku typu raw JSON definujte parametry těla a vložte jejich zástupné symboly @name@ do šablony. Přidejte odpovídající hlavičku Content-Type vyžadovanou vaším koncovým bodem. Například s řetězcovým parametrem name a parametrem typu pole řetězců tags:
{
"name": "@name@",
"tags": @tags@
}
Toto je šablona, nikoli doslovný formát JSON až do chvíle nahrazení hodnot. Zástupné symboly pro pole nesmí být uzavřeny v uvozovkách. Každý definovaný parametr těla musí být v šabloně použit, pokud je aktivní editor těla požadavku raw. Během testování zkontrolujte vygenerovaný požadavek, včetně textu obsahujícího uvozovky nebo speciální znaky.
4. Přidejte ověřovací hlavičky
Pomocí Add header (Přidat hlavičku) definujte hlavičky, které API očekává. Pro bearer token použijte název hlavičky Authorization, zdroj hodnoty Constant (Konstanta) a hodnotu Bearer YOUR_RESTRICTED_TOKEN.
Uchovávejte tajné klíče mimo prompty a adresy URL. Vyhněte se operacím, které vracejí přihlašovací tokeny modelu a spoléhají na to, že je instrukce skryjí. Dejte přednost integračnímu koncovému bodu na straně serveru, který sám spravuje své ověřování a zpřístupňuje pouze povolenou operaci.
5. Uložení a otestování požadavku
- V editoru operace klikněte na Save changes (Uložit změny). Na rozdíl od běžného nastavení chatbota má tento editor samostatné tlačítko pro uložení.
- Klikněte na Test API Operation (Otestovat operaci API). Dokud nejsou změny uloženy, je toto tlačítko neaktivní.
- Zadejte reprezentativní hodnoty parametrů. U testovacích vstupů typu pole použijte hodnoty oddělené čárkami.
- Test spouštějte pouze s daty, ke kterým máte oprávnění pro čtení nebo úpravy.
- Zkontrolujte stavový kód, tělo odpovědi, URL požadavku, hlavičky, tělo a případná varování zobrazená ve výsledcích.
- Opravte chyby, uložte změny a podle potřeby postup opakujte.
Nesdílejte výstup testu obsahující přihlašovací údaje. Pokud je to možné, vracejte pouze relevantní stránkovaná data: velké odpovědi se mohou zkrátit dříve, než dorazí k modelu.
6. Přiřazení operace k chatbotovi
Otevřete svého chatbota a přejděte do Settings > Actions (Nastavení > Akce). Pomocí tlačítka plus přidejte akci, vyhledejte svou operaci v části vlastních API a přiřaďte ji nebo povolte. Samotné vytvoření integrace na úrovni účtu nezpřístupní každou operaci automaticky každému chatbotovi.
Zkontrolujte instrukce k akci a dostupná nastavení zabezpečení a poté počkejte na potvrzení o uložení. Informace o editoru akcí najdete v článku AI actions (Akce AI).
7. Vysvětlete, kdy ji použít
Otevřete Settings > Role & Behavior (Nastavení > Role a chování).
Pokud používáte vlastní instrukce role, vyberte Custom Role Definition (Vlastní definice role) a přidejte přesné pravidlo, například: "Pokud se návštěvník zeptá, zda je produkt skladem, zavolejte getProductDetails s jeho ID produktu. Uveďte vrácenou dostupnost. Pokud vyhledání selže, vysvětlete, že dostupnost nebylo možné ověřit."
Zachovejte ostatní užitečné instrukce chatbota. Počkejte na potvrzení uložení a poté pomocí náhledu v části Overview (Přehled) otestujte realistické dotazy, chybějící parametry, chyby i neautorizované požadavky. Konverzace v náhledu mohou vyvolat skutečné operace.
Vyvolání ze strany AI není zaručené ani nemusí proběhnout pouze jednou. Testujte s modelem vybraným pro vašeho chatbota; nepředpokládejte, že samotný název modelu zaručuje správné použití nástroje.
Zabezpečení a řešení potíží
Váš koncový bod musí požadavky ověřovat (autentizovat) a autorizovat přístup každého uživatele předtím, než vrátí citlivé informace nebo provede změnu. Klientské ID z prohlížeče, e-mail, číslo objednávky ani pole kontextu nejsou dostatečným důkazem identity. Pokud předáváte token konkrétního uživatele prostřednictvím kontextu klienta, váš server jej musí ověřit.
Vracejte pouze pole, která chatbot potřebuje - například stav objednávky namísto celého profilu zákazníka. Instrukce v promptu mohou usměrnit formulaci odpovědi, nemohou však zaručit, že citlivá data předaná modelu zůstanou skrytá.
Pokud požadavek v testovacím editoru uspěje, ale v konverzaci selže, zkontrolujte připojenou akci, její aktivní stav, instrukce, povinné parametry a dostupný kontext. Pokud selžou obě varianty, zkontrolujte URL, metodu HTTP, autentizaci, vykreslené tělo požadavku a protokoly svého koncového bodu. Vyhněte se opakovanému spouštění zápisových operací, dokud nezjistíte, zda předchozí požadavek uspěl.