Персонализираните API интеграции позволяват на Вашия чатбот да изисква актуална информация в реално време от Вашата ERP система, склад, CRM или друга услуга. Те могат също така да правят промени, като например създаване на час за среща. Дадена интеграция съхранява базовия URL адрес; всяка операция дефинира една конкретна заявка за извикване. След това прикачвате избраните операции към даден чатбот като AI действия (AI actions).
Преди да започнете
Проверете дали Вашият акаунт включва персонализирани API интеграции (Custom API integrations). Нужни са Ви URL адресът на крайната точка (endpoint), HTTP методът, имената и типовете на параметрите, изискванията за автентикация и примерен отговор. Крайната точка трябва да бъде достъпна от сървърите на ChatLab; localhost на Вашия компютър не е производствена крайна точка.
Използвайте HTTPS и тестова услуга или тестови записи за настройката. Тестовата заявка реално извиква крайната точка, така че POST, PATCH или DELETE може да промени външни данни. Направете операциите безопасни за повторение, където е възможно.
1. Създаване на интеграция
- Отворете Custom Integrations в главното меню за навигация.
- Кликнете върху + Define API Integration.
- Въведете API name (Име на API) и API Base URL (Базов URL адрес на API), например
https://api.example.com. - Кликнете върху Create API Integration.
- В записа му в списъка кликнете върху View, след което върху + Define API Operation.
2. Дефинирайте операцията
Задайте на операцията разпознаваем етикет и машинночетимо Име на операция (Operation name), например getProductDetails. Използвайте само букви и цифри за името на операцията - без интервали или долни черти. Опишете какво прави операцията и кога чатботът трябва да я използва.
Въведете релативния URI адрес, например /v1/products/@productId@. Базовият URL и URI образуват адреса на заявката.
Някои съществуващи екранни снимки показват по-стари примерни имена или плейсхолдъри с фигурни скоби. Следвайте текущия синтаксис по-долу: имена на операции като getProductDetails и плейсхолдъри за параметри, оградени с @.
Параметри на пътя и на заявката (Path and Query Parameters)
Кликнете върху Add path variable (Добавяне на променлива на пътя), за да дефинирате productId. Задайте нейния тип данни и източник на стойност, след което включете @productId@ в URI адреса. Променливите на пътя са задължителни и всяка дефинирана променлива на пътя трябва да присъства в URI адреса, преди да можете да запазите или тествате.
Използвайте Add query parameter (Добавяне на параметър на заявката) за параметри като limit или language, които стоят след въпросителния знак в URL адреса. Въведете името, очаквано от Вашето API, неговия тип, описание и източник на стойност.
Наличните източници на стойност включват:
- Provided by user or chatbot (Предоставено от потребител или чатбот): моделът подава стойност от разговора. Обяснете очаквания формат и маркирайте задължителните стойности по подходящ начин.
- Constant (Константа): стойност, конфигурирана в операцията, като например фиксиран идентификатор на профил или ограничени идентификационни данни за API.
- Random value (Произволна стойност): автоматично генерирана стойност.
- Client context (Клиентски контекст): стойност, подадена от хостващия уебсайт, ако е налична за Вашия профил. Вижте Chat API.
Скаларните типове включват string, integer, double и boolean. Параметрите в тялото на заявката (body) поддържат също масиви от string и integer.
3. Конфигурирайте метода и тялото (Method and Body)
Изберете GET, POST, PUT, PATCH или DELETE, за да съответства на Вашата крайна точка (endpoint). За методи, различни от GET, редакторът предлага съдържание на заявката от тип raw или form-data.
За тяло в необработен JSON формат (raw JSON) дефинирайте параметрите на тялото и вмъкнете техните плейсхолдъри @name@ в шаблона. Добавете съответния хедър Content-Type, изискван от Вашата крайна точка. Например, с текстов параметър (string) name и масив от текстови низове (string-array) tags:
{
"name": "@name@",
"tags": @tags@
}
Това е шаблон, а не буквален JSON, докато не се извърши заместването. Плейсхолдърите за масиви не трябва да бъдат оградени с кавички. Всеки дефиниран параметър на тялото трябва да бъде използван в шаблона, когато е приложен редакторът за raw тяло. Проверете генерираната заявка по време на тестването, включително текст, съдържащ кавички или специални символи.
4. Добавяне на заглавки за удостоверяване (Authentication Headers)
Използвайте Add header (Добавяне на заглавка), за да дефинирате заглавките, очаквани от API. За bearer токен използвайте име на заглавката Authorization, източник на стойността Constant (Константа) и стойност Bearer YOUR_RESTRICTED_TOKEN.
Не включвайте тайни ключове и пароли в промптовете и в URL адресите. Избягвайте операции, които връщат токени за вход към модела и разчитат на инструкции да ги скрият. Препоръчително е да използвате сървърна крайна точка за интеграция, която управлява собственото си удостоверяване и предоставя достъп само до разрешената операция.
5. Запазете и тествайте заявката
- Кликнете върху Save changes (Запазване на промените) в редактора на операции. За разлика от стандартните настройки на чатбота, този редактор разполага с изричен бутон за запазване.
- Кликнете върху Test API Operation (Тестване на API операцията). Бутонът е деактивиран, докато има незапазени промени.
- Въведете представителни стойности на параметрите. За тестови масиви от данни използвайте стойности, разделени със запетая.
- Стартирайте теста само с данни, за чието четене или промяна имате оторизация.
- Проверете кода за състояние (status code), тялото на отговора (response body), URL адреса на заявката, хедърите, тялото на заявката и всяко предупреждение, показано в резултатите.
- Коригирайте грешките, запазете промените и повторете, ако е необходимо.
Не споделяйте резултати от теста, съдържащи идентификационни данни. Връщайте фокусирани данни с разбивка на страници (пагинация), където е възможно: твърде големите отговори могат да бъдат отрязани, преди да достигнат до модела.
6. Прикачване на операцията към чатбот
Отворете Вашия чатбот, след което отидете в Settings > Actions (Настройки > Действия). Използвайте бутона плюс, за да добавите действие, намерете Вашата операция под персонализираните API интеграции и я прикачете или активирайте. Самото създаване на интеграция на ниво акаунт не прави всяка операция автоматично достъпна за всеки чатбот.
Прегледайте инструкциите на действието и наличните настройки за сигурност, след което изчакайте статуса за запазване. Вижте AI действия за редактора на действия.
7. Обяснете кога да се използва
Отворете Settings > Role & Behavior (Настройки > Роля и поведение).
Ако използвате персонализирани инструкции за ролята, изберете Custom Role Definition (Персонализирана дефиниция на роля) и добавете точно правило, например: "Когато посетителят попита дали даден продукт е наличен, извикайте getProductDetails с идентификатора на продукта. Съобщете върнатата информация за наличността. Ако проверката е неуспешна, обяснете, че наличността не може да бъде проверена."
Запазете останалите полезни инструкции на чатбота. Изчакайте статусът да се промени на запазен, след което използвайте прегледа в Overview (Преглед), за да тествате реалистични въпроси, липсващи параметри, грешки и неоторизирани заявки. Разговорите в тестовия преглед могат да задействат реални операции.
Извикването от страна на AI не е гарантирано, нито непременно еднократно. Тествайте с модела, избран за Вашия чатбот; не приемайте, че самото име на модела гарантира правилно използване на инструментите.
Сигурност и отстраняване на неизправности
Вашата крайна точка (endpoint) трябва да автентикира заявките и да оторизира достъпа на всеки потребител, преди да върне поверителна информация или да извърши промяна. Подадените от браузъра клиентски идентификатор (client ID), имейл, номер на поръчка или поле с контекст не са достатъчно доказателство за самоличност. Ако предавате токен за конкретен потребител през клиентския контекст, Вашият сървър трябва задължително да го валидира.
Връщайте само полетата, от които чатботът има нужда - например статус на поръчката вместо пълен потребителски профил. Инструкциите в системния промпт могат да насочват формулировката, но не могат да гарантират, че поверителните данни, върнати към модела, ще останат скрити.
Ако заявката е успешна в тестовия редактор, но не работи в разговор, проверете прикаченото действие, дали е активирано, неговите инструкции, задължителните му параметри и наличния контекст. Ако и двете се провалят, проверете URL адреса, HTTP метода, автентикацията, генерираното тяло на заявката и логовете на Вашата крайна точка. Избягвайте многократни повторни опити за операция за запис, докато не разберете дали предишната заявка е била успешна.