Vlastné integrácie API umožňujú vášmu chatbotovi vyžiadať si aktuálne informácie z vášho ERP, skladu, CRM alebo inej služby. Môžu vykonávať aj zmeny, napríklad vytvoriť termín schôdzky. Integrácia uchováva základnú URL adresu; každá operácia definuje jednu volateľnú požiadavku. Vybrané operácie potom priradíte k chatbotovi ako akcie umelej inteligencie (AI actions).
Skôr než začnete
Skontrolujte, či váš účet obsahuje vlastné integrácie API (Custom API integrations). Budete potrebovať URL adresu koncového bodu (endpoint), metódu HTTP, názvy a typy parametrov, požiadavky na autentifikáciu a vzorovú odpoveď. Koncový bod musí byť dostupný zo serverov ChatLab; localhost vo vašom počítači nie je produkčný koncový bod.
Na nastavenie použite HTTPS a testovaciu službu alebo testovacie záznamy. Testovacia požiadavka skutočne volá daný koncový bod, takže POST, PATCH alebo DELETE môžu zmeniť externé dáta. Ak je to možné, nastavte operácie tak, aby ich bolo bezpečné opakovať.
1. Vytvorenie integrácie
- V hlavnej navigácii otvorte Custom Integrations (Vlastné integrácie).
- Kliknite na + Define API Integration (Definovať integráciu API).
- Zadajte API name (Názov API) a API Base URL (Základná URL API), napríklad
https://api.example.com. - Kliknite na Create API Integration (Vytvoriť integráciu API).
- V jej zázname v zozname kliknite na View (Zobraziť) a potom na + Define API Operation (Definovať operáciu API).
2. Definujte operáciu
Pomenujte operáciu rozpoznateľným štítkom a strojovo čitateľným názvom Operation name (Názov operácie), ako napríklad getProductDetails. Pre názov operácie používajte iba písmená a číslice, nie medzery ani podčiarkovníky. Popíšte, čo operácia robí a kedy by ju mal chatbot použiť.
Zadajte relatívne URI, napríklad /v1/products/@productId@. Základná URL a URI tvoria adresu požiadavky.
Niektoré existujúce snímky obrazovky zobrazujú staršie ukážkové názvy alebo zástupné symboly v zložených zátvorkách. Postupujte podľa nižšie uvedenej aktuálnej syntaxe: názvy operácií ako getProductDetails a zástupné symboly parametrov ohraničené pomocou @.
Parametre cesty a dopytu (Path a Query)
Kliknite na Add path variable (Pridať premennú cesty) a definujte productId. Nastavte jej dátový typ a zdroj hodnoty, a potom zahrňte @productId@ do URI. Premenné cesty sú povinné a každá definovaná premenná cesty sa musí objaviť v URI skôr, ako budete môcť operáciu uložiť alebo otestovať.
Možnosť Add query parameter (Pridať parameter dopytu) použite pre parametre ako limit alebo language, ktoré patria za otáznik v URL. Zadajte názov, ktorý vaše API očakáva, jeho typ, popis a zdroj hodnoty.
Medzi dostupné zdroje hodnôt patria:
- Provided by user or chatbot (Poskytnuté používateľom alebo chatbotom): model dodá hodnotu z konverzácie. Vysvetlite očakávaný formát a primerane označte povinné hodnoty.
- Constant (Konštanta): hodnota nakonfigurovaná v operácii, ako je fixný identifikátor účtu alebo prístupové údaje API s obmedzenými oprávneniami.
- Random value (Náhodná hodnota): hodnota vygenerovaná automaticky.
- Client context (Kontext klienta): hodnota odovzdaná hostiteľskou webovou stránkou, ak je pre váš účet dostupná. Pozrite si Chat API.
Medzi skalárne typy patria string (reťazec), integer (celé číslo), double (číslo s pohyblivou rádovou čiarkou) a boolean (logická hodnota). Parametre v tele požiadavky (body) podporujú aj polia reťazcov a celých čísel (string a integer arrays).
3. Nakonfigurujte metódu a telo (Method a Body)
Vyberte GET, POST, PUT, PATCH alebo DELETE podľa vášho koncového bodu. Pri iných metódach ako GET editor ponúka formát požiadavky raw (nespracovaný) alebo form-data.
Pri tele typu raw JSON definujte parametre tela a vložte ich zástupné symboly @name@ do šablóny. Pridajte príslušnú hlavičku Content-Type požadovanú vaším koncovým bodom. Napríklad pri reťazcovom parametri name a parametri poľa reťazcov tags:
{
"name": "@name@",
"tags": @tags@
}
Toto je šablóna, ktorá sa stane platným JSON až po dosadení hodnôt. Zástupné symboly poľa nesmú byť v úvodzovkách. Každý definovaný parameter tela sa musí v šablóne použiť, keď je aktívny editor raw tela. Počas testovania skontrolujte vykreslenú požiadavku, vrátane textu obsahujúceho úvodzovky alebo špeciálne znaky.
4. Pridajte overovacie hlavičky
Pomocou možnosti Add header (Pridať hlavičku) zadefinujte hlavičky, ktoré API očakáva. V prípade bearer tokenu použite názov hlavičky Authorization, zdroj hodnoty Constant (Konštanta) a hodnotu Bearer YOUR_RESTRICTED_TOKEN.
Uchovávajte tajné kľúče mimo promptov a adries URL. Vyhnite sa operáciám, ktoré vracajú prihlasovacie tokeny modelu a spoliehajú sa na inštrukcie, ktoré ich majú skryť. Uprednostnite integračný koncový bod na strane servera, ktorý spravuje vlastné overovanie a sprístupňuje iba povolenú operáciu.
5. Uloženie a otestovanie požiadavky
- Kliknite na Save changes (Uložiť zmeny) v editore operácie. Na rozdiel od bežných nastavení chatbota (Settings) má tento editor samostatné tlačidlo na uloženie.
- Kliknite na Test API Operation (Otestovať operáciu API). Kým nie sú zmeny uložené, toto tlačidlo je neaktívne.
- Zadajte reprezentatívne hodnoty parametrov. Pre testovacie vstupy typu pole použite hodnoty oddelené čiarkou.
- Test spúšťajte iba s údajmi, ktoré máte oprávnenie čítať alebo meniť.
- Skontrolujte stavový kód, telo odpovede, URL požiadavky, hlavičky, telo a akékoľvek varovania zobrazené vo výsledkoch.
- Opravte chyby, uložte zmeny a podľa potreby postup zopakujte.
Nezdieľajte výstupy testov obsahujúce prihlasovacie údaje. Kde je to možné, vracajte cielené, stránkované údaje: veľké odpovede sa môžu skrátiť ešte predtým, ako sa dostanú k modelu.
6. Priradenie operácie k chatbotovi
Otvorte svojho chatbota a potom prejdite na Settings > Actions (Nastavenia > Akcie). Pomocou tlačidla plus pridajte akciu, nájdite svoju operáciu v časti vlastných API (custom APIs) a priraďte ju alebo povoľte. Samotné vytvorenie integrácie na úrovni účtu nesprístupní každú operáciu automaticky každému chatbotovi.
Skontrolujte inštrukcie akcie a dostupné bezpečnostné nastavenia, potom počkajte na stav uloženia. Informácie o editore akcií nájdete v časti Akcie AI.
7. Vysvetlite, kedy ju použiť
Otvorte Settings > Role & Behavior (Nastavenia > Rola a správanie).
Ak používate vlastné inštrukcie pre rolu, vyberte Custom Role Definition (Vlastná definícia roly) a pridajte presné pravidlo, napríklad: „Keď sa návštevník opýta, či je produkt na sklade, zavolajte getProductDetails s jeho ID produktu. Oznámte vrátenú dostupnosť. Ak vyhľadávanie zlyhá, vysvetlite, že dostupnosť sa nepodarilo overiť.“
Ostatné užitočné inštrukcie chatbota ponechajte. Počkajte na potvrdenie uloženia a potom pomocou náhľadu v časti Overview (Prehľad) otestujte realistické otázky, chýbajúce parametre, chyby a neautorizované požiadavky. Konverzácie v náhľade môžu spúšťať skutočné operácie.
Vyvolanie nástroja umelou inteligenciou nie je zaručené a nemusí prebehnúť iba raz. Testujte s modelom vybratým pre vášho chatbota - nespoliehajte sa na to, že samotný názov modelu zaručuje správne použitie nástroja.
Zabezpečenie a riešenie problémov
Váš koncový bod musí požiadavky autentifikovať a autorizovať prístup každého používateľa predtým, ako vráti citlivé informácie alebo vykoná zmenu. Klientske ID z prehliadača, e-mail, číslo objednávky ani pole kontextu nepredstavujú dostatočný dôkaz totožnosti. Ak odovzdávate token jednotlivého používateľa prostredníctvom klientskeho kontextu, váš server ho musí overiť.
Vracajte iba polia, ktoré chatbot potrebuje, napríklad stav objednávky namiesto celého profilu zákazníka. Inštrukcie v prompte môžu usmerniť formuláciu odpovede, nedokážu však zaručiť, že citlivé údaje vrátené modelu zostanú skryté.
Ak požiadavka v testovacom editore uspeje, ale v konverzácii nie, skontrolujte pripojenú akciu, jej stav zapnutia, inštrukcie, povinné parametre a dostupný kontext. Ak zlyhajú oba prípady, skontrolujte URL, metódu HTTP, autentifikáciu, vygenerované telo požiadavky a logy vášho koncového bodu. Vyhnite sa opakovanému odosielaniu operácie zápisu, kým nezistíte, či predchádzajúca požiadavka uspela.