Елемент API запит в чат-ботах

Автоматизувати процес стало ще простіше з API запитами. За допомогою цього функціоналу ви зможете, наприклад, за назвою міста повідомляти погоду, за назвою товару здійснювати пошук та виводити результат у чат-бот, за даними підписника реєструвати його на захід або створювати замовлення.

Це працює так: ви надсилаєте запити даних у зовнішні системи про будь-яку інформацію, якою цікавиться ваш користувач або створюєте новий об’єкт. У відповідь ви дістаєте дані, які можна відразу видавати користувачу в повідомленні або записувати в змінну чат-бота.

Як надіслати запит на отримання даних

Елемент Запит API (API Request) надсилає запит на зовнішній сервер, використовуючи дані вашого чат-бота. Додайте URL-адресу запиту, заголовки та тіло, а потім вкажіть, як обробляти відповідь.

Налаштування запиту

Перетягніть елемент Запит API (API Request) на робоче поле, з’єднайте його з елементом, після якого потрібно отримати інформацію.

Виберіть тип запиту:

• GET запит зазвичай використовують для отримання наявних даних;
• POST запит зазвичай використовують для створення нового об’єкта в системі та отримання інформації про нього.

Введіть URL-адресу, на яку буде надіслано запит. У запиті можете використовувати користувальницькі та глобальні змінні вашого чат-бота та модифікувати їх. Щоб обрати змінні, натисніть {} у правому верхньому куті текстового поля. Щоб знайти змінну, у верхній частині дропдауну змінних введіть її назву в полі пошуку Пошук за назвою (Find by name).

Ви можете додавати заголовки запиту, наприклад, для авторизації запитів. Також можна використовувати змінні бота в заголовках запиту.

Якщо ви використовуєте запит POST, введіть тіло запиту в потрібному полі в JSON з параметрами. Ви також можете модифікувати тіло запиту.

Натисніть Перевірити запит (Test Request), щоб перевірити надсилання даних. Також перевірка стане в пригоді для розпізнавання даних під час подальшого налаштування.

Конвертація типів даних змінних у тілі запиту

Коли ви вставляєте змінну чат-бота в тіло запиту, чат-бот за замовчуванням обгортає її в лапки та надсилає як рядок. Якщо API очікує інший тип даних — число, булеве значення чи вкладений обʼєкт — використовуйте модифікатор тіла запиту.

Модифікатор тіла запиту — це індикатор типу з двокрапкою, який ставиться після назви змінної: {{variable_name}}::type. Він конвертує значення у вказаний тип даних і прибирає навколишні лапки з JSON-виведення.

Доступні модифікатори:

Наприклад, якщо ви використовуєте таке тіло запиту:

{
  "name": "{{full_name}}",
  "id": "{{crm_id}}::int",
  "stage_id": 2
}

Ваш чат-бот замінить змінні на їхні значення та надішле:

{
  "name": "John",
  "id": 123,
  "stage_id": 2
}

Чат-боти надсилають значення id як число. Навколишні лапки прибираються автоматично.

Модифікатори тіла запиту відрізняються від модифікаторів змінних. Запис із двокрапкою застосовується лише в елементі Запит API (API Request) і використовується для конвертації типів даних у JSON.

Якщо ви введете змінну в тіло запиту без лапок — наприклад, "key": {{var}} — редактор чат-бота позначить тіло як невалідний JSON.

Як використовувати отримані дані

У разі успішного запиту ви отримаєте тіло відповіді та користувач пройде гілкою Виконано.

По гілці Виконано (Done) будуть йти всі відповіді запитів зі статусом 2хх. Відповіді запитів з іншими статусами підуть по гілці Помилка (Error) і дані не можна буде використовувати. Читайте докладніше: Як продовжити ланцюжок у разі помилки запиту.

Отримані дані можна використати один раз у наступному текстовому блоці, записати у змінну чат-бота для багаторазового використання або надіслати картки повідомлень на основі зазначеного масиву.

API може повертати відповідь до 65 КБ в розмірі. Часовий ліміт на обробку запиту становить 60 секунд.

Використання даних зі збереженням у змінну

Щоб зберегти дані у змінні для подальшого використання, в елементі Запит API (API Request) перейдіть у вкладку Зберігати значення (Save values) і в налаштуваннях відповідностей натисніть Додати (Add).

З поля відповіді виберіть ключ, значення змінної якого вам потрібно використовувати.

Виберіть змінну, до якої потрібно зберігати значення. Ви можете зберегти значення до 1024 символів з поля у відповіді.

Коли ви зберегли необхідну кількість змінних, натисніть Застосувати (Apply) та перейдіть до створення наступного блоку.

У прикладі нижче ми створили замовлення, дістали дані у відповідь із нашої CRM, зберегли їх у змінні та повідомляємо користувачеві для швидкої ідентифікації замовленої послуги чи товару.

Для користувача спілкування з вашим чат-ботом виглядає так:

Використання даних у вигляді виразу JSON Path

Якщо вам не потрібно записувати дані до змінних, можете використовувати отриману інформацію вставкою виразу шляху JSON структури.

Дані, які ви не записуєте, можна використовувати лише один раз у наступному текстовому блоці.

У тексті повідомлення додайте JSON Path {{$['somekey']['nestedkey']}}.

Щоб використовувати заголовки, cookies, статус-коди та іншу системну інформацію, отриману в результаті запиту, зазначте ці дані у вигляді {{$$['headers']}, {{$$['cookies']}} або {{$$['data']}} у повідомленні.

Таким чином, ви можете використовувати інтеграції з сервісами, що потребують даних авторизації, які передаються до cookies.

Для користувача спілкування з вашим чат-ботом із цього прикладу виглядає так:

Використання для надсилання карток

На платному тарифі доступне також надсилання карток, сформованих із даних, які будуть отримані у відповідь на запит. Для цього перейдіть у вкладку Відправляти повідомлення (Send messages) і заповніть поля форми даними з отриманого масиву.

Дізнайтеся більше: Як надсилати картки повідомлень у чат-ботах.

Як продовжити ланцюжок у разі помилки запиту

Розгалузьте сценарій і у разі неуспішного API запиту продовжити ланцюжок по гілці Помилка (Error). Наприклад, ви можете повідомити про помилку та перепитати необхідні дані, якщо вони не збігаються, або покликати менеджера.

Ви також можете передати відповідь сервера з помилкою. Це допоможе вам показати користувачам повідомлення про помилку або записати деталі помилки для налагодження. Щоб звернутися до конкретного поля у відповіді з помилкою, використовуйте вираз JSON Path, наприклад {{$['status_code']}}.

Оновлено: 01.07.2024