Кастомні інтеграції API дозволяють вашому чатботу запитувати актуальну інформацію з вашої ERP, складу, CRM або іншого сервісу. Вони також можуть вносити зміни, наприклад створювати запис на прийом. Інтеграція зберігає базову URL-адресу; кожна операція визначає один запит, доступний для виклику. Потім ви підключаєте вибрані операції до чатбота як дії ШІ.
Перш ніж почати
Переконайтеся, що ваш тарифний план включає кастомні інтеграції API. Вам знадобляться URL-адреса кінцевої точки, метод HTTP, назви та типи параметрів, вимоги до автентифікації та приклад відповіді. Кінцева точка має бути доступною із серверів ChatLab; localhost на вашому комп'ютері не є робочою кінцевою точкою.
Використовуйте HTTPS і тестовий сервіс або тестові записи для налаштування. Тестовий запит дійсно звертається до кінцевої точки, тому POST, PATCH або DELETE можуть змінити зовнішні дані. За можливості робіть операції безпечними для повторення.
1. Створіть інтеграцію
- Відкрийте Custom Integrations (Кастомні інтеграції) в головному меню навігації.
- Натисніть + Define API Integration (+ Визначити інтеграцію API).
- Введіть API name (Назва API) та API Base URL (Базова URL-адреса API), наприклад
https://api.example.com. - Натисніть Create API Integration (Створити інтеграцію API).
- У списку біля створеного запису натисніть View (Переглянути), а потім + Define API Operation (+ Визначити операцію API).
2. Визначте операцію
Вкажіть для операції зрозумілу назву та машиночитну Operation name (Назва операції), наприклад getProductDetails. Для назви операції використовуйте лише літери та цифри, без пробілів або знаків підкреслення. Опишіть, що робить операція та коли чатбот має її використовувати.
Введіть відносний URI, наприклад /v1/products/@productId@. Базова URL-адреса та URI формують адресу запиту.
Деякі наявні знімки екрана показують застарілі приклади назв або заповнювачі у фігурних дужках. Дотримуйтеся поточного синтаксису, наведеного нижче: назви операцій на зразок getProductDetails та заповнювачі параметрів, оточені символами @.
Параметри шляху та запиту
Натисніть 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). Параметри тіла запиту також підтримують масиви рядків і цілих чисел.
3. Налаштуйте метод і тіло запиту
Виберіть GET, POST, PUT, PATCH або DELETE відповідно до вашої кінцевої точки. Для методів, відмінних від GET, редактор пропонує формат вмісту запиту raw або form-data.
Для тіла у форматі raw JSON визначте параметри тіла та вставте їхні заповнювачі @name@ у шаблон. Додайте відповідний заголовок Content-Type, якого вимагає ваша кінцева точка. Наприклад, для рядкового параметра name і параметра-масиву рядків tags:
{
"name": "@name@",
"tags": @tags@
}
Це шаблон, а не буквальний JSON до моменту підстановки значень. Заповнювачі масивів не повинні бути в лапках. Кожен визначений параметр тіла має використовуватися в шаблоні, коли застосовується редактор raw-тіла. Перевірте згенерований запит під час тестування, зокрема текст із лапками чи спеціальними символами.
4. Додайте заголовки автентифікації
Використовуйте Add header (Додати заголовок), щоб визначити заголовки, які очікує API. Для bearer-токена вкажіть назву заголовка Authorization, джерело значення Constant і значення Bearer YOUR_RESTRICTED_TOKEN.
Не зберігайте конфіденційні дані в інструкціях (prompts) та URL-адресах. Уникайте операцій, які повертають токени входу моделі та покладаються на інструкції, щоб їх приховати. Надавайте перевагу кінцевій точці інтеграції на стороні сервера, яка сама керує своєю автентифікацією та відкриває лише дозволену операцію.
5. Збережіть і протестуйте запит
- Натисніть Save changes (Зберегти зміни) в редакторі операцій. На відміну від звичайних налаштувань чатбота, у цьому редакторі є окрема кнопка збереження.
- Натисніть Test API Operation (Тестувати операцію API). Вона залишається неактивною, доки зміни не збережено.
- Введіть типові значення параметрів. Для тестових даних масиву використовуйте значення, розділені комами.
- Запускайте тест лише з даними, до яких ви маєте право доступу на читання чи зміну.
- Перевірте код статусу, тіло відповіді, URL-адресу запиту, заголовки, тіло та будь-які попередження в результатах.
- За потреби виправте помилки, збережіть і повторіть спробу.
Не діліться результатами тестування, які містять облікові дані. За можливості повертайте лаконічні дані з пагінацією: великі відповіді можуть обрізатися ще до того, як дістануться моделі.
6. Підключіть операцію до чатбота
Відкрийте вашого чатбота, потім перейдіть у Settings > Actions (Налаштування > Дії). За допомогою кнопки з плюсом додайте дію, знайдіть вашу операцію в розділі кастомних API та підключіть або ввімкніть її. Створення інтеграції на рівні облікового запису саме по собі не робить кожну операцію доступною для кожного чатбота.
Перегляньте інструкції для дії та доступні параметри безпеки, потім зачекайте на підтвердження збереження статусу. Докладніше про роботу з редактором дій читайте в розділі дії ШІ.
7. Поясніть, коли її використовувати
Перейдіть у Settings > Role & Behavior (Налаштування > Роль і поведінка).
Якщо ви використовуєте власні інструкції щодо ролі, виберіть Custom Role Definition (Власне визначення ролі) та додайте чітке правило, наприклад: "When the visitor asks whether a product is in stock, call getProductDetails with its product ID. Report the returned availability. If the lookup fails, explain that availability could not be checked."
Збережіть інші корисні інструкції чатбота. Дочекайтеся статусу збереження, а потім відкрийте попередній перегляд Overview (Огляд), щоб протестувати реалістичні запитання, відсутні параметри, помилки та неавторизовані запити. Розмови в режимі попереднього перегляду можуть виконувати реальні операції.
Виклик інструментів штучним інтелектом не гарантується і не обов'язково виконується лише один раз. Проводьте тестування саме з тією моделлю, яка обрана для вашого чатбота; не сподівайтеся, що лише назва моделі гарантує правильне використання інструментів.
Безпека та усунення несправностей
Ваша кінцева точка має автентифікувати запити та перевіряти права доступу кожного користувача, перш ніж повертати конфіденційні дані або вносити зміни. Надані браузером ідентифікатор клієнта, електронна пошта, номер замовлення чи поле контексту не є достатнім підтвердженням особи. Якщо ви передаєте індивідуальний токен користувача через клієнтський контекст, ваш сервер обов'язково має його перевірити.
Повертайте лише ті поля, які необхідні чатботу, наприклад статус замовлення замість повного профілю клієнта. Інструкції в промптах можуть скерувати формулювання, але не можуть гарантувати, що передані моделі конфіденційні дані залишаться прихованими.
Якщо запит успішно виконується в редакторі тестування, але не в діалозі, перевірте підключену дію, її статус увімкнення, інструкції, обов'язкові параметри та доступний контекст. Якщо запит не вдається в обох випадках, перевірте URL-адресу, метод HTTP, автентифікацію, сформоване тіло запиту та журнали вашої кінцевої точки. Уникайте багаторазових повторних спроб для операцій запису, доки не переконаєтеся, чи був успішним попередній запит.