API-запросы

Что такое блок «API-запрос»

Блок «API-запрос» позволяет боту обращаться к любому внешнему HTTP-сервису — вашему бэкенду, CRM, базе данных через REST API или любому другому сервису с HTTP-интерфейсом. Ответ автоматически парсится и сохраняется в переменные.

В отличие от Интеграций (которые работают с готовыми сервисами по шаблону), блок API-запроса — универсальный и полностью настраивается вручную.

Настройка запроса

Поле	Описание
Метод	GET, POST, PUT, PATCH, DELETE
URL	Адрес эндпоинта; поддерживает `{{переменные}}`
Заголовки (Headers)	Пары ключ-значение; например `Authorization: Bearer {{token}}`
Тело запроса (Body)	JSON или form-data; поддерживает `{{переменные}}`
Переменная результата	Имя переменной для сохранения ответа

Пример URL с переменной

https://api.example.com/users/{{user_id}}/orders

Пример тела POST-запроса

{
  "name": "{{user_name}}",
  "email": "{{user_email}}",
  "phone": "{{phone}}"
}

Работа с ответом

Ответ API сохраняется в указанную переменную. Если ответ — JSON-объект, поля доступны через dot-notation:

{{result.status}}      → поле "status" в ответе
{{result.data.id}}     → вложенное поле data.id
{{result.items.0.name}} → первый элемент массива items

Кеширование ответов

Если ответ API не меняется часто, включите кеширование — запрос выполнится один раз, а последующие обращения будут мгновенными.

Настройка	Описание
TTL	Время жизни кеша: 1–60 минут или бессрочно

Кеш хранится на уровне бота. При изменении URL (в т.ч. переменных в нём) кеш не используется.

Polling-режим

Некоторые API работают асинхронно: запрос запускает задачу, а результат нужно «опрашивать» периодически. Для таких сервисов включите режим polling:

Включите «Ожидать результата».
Укажите поле статуса в ответе (например, status).
Укажите значение готовности (например, done или completed).
Бот будет повторять запрос с интервалом, пока поле не примет нужное значение.

Пример: генерация изображения через внешний API — запрос запускается, затем бот периодически проверяет статус и продолжает сценарий, когда изображение готово.

Фоновый процесс

Если обработка запроса может занять более 3 минут, включите опцию «Фоновый процесс» (доступна только при включённом polling).

⚠️ Важно: фоновый процесс является блокирующей операцией — все последующие блоки текущей команды не будут выполнены. Вместо этого настройте следующую команду, которая будет вызвана автоматически после завершения обработки.

При включении фонового процесса webhook-обработчик немедленно завершается, а опрос API выполняется в фоновой очереди задач. Схема продолжается с указанной следующей ноды, когда условие polling-а выполнено или исчерпаны попытки.

Лоадер

При включённом «Выводить лоадер» бот с самого начала пришлёт сообщение с индикатором прогресса, который будет обновляться в реальном времени:

Настройка	Описание
Дизайн лоадера	Стиль прогресс-бара: квадраты `🟩⬜` или кружки `🟢⚪`
Текст под лоадером	Подпись под прогресс-баром (по умолчанию «Обработка запроса…»)
Среднее время обработки	Ожидаемое время выполнения в минутах — используется для вычисления процента прогресса

Каждый из 10 сегментов лоадера соответствует 10 % указанного времени. Например, при настройке 5 минут: через 2.5 мин будет показано 5 заполненных сегментов из 10. По завершении обработки сообщение с лоадером автоматически удаляется.

Переменные

Ответ API сохраняется в указанную переменную в обычном формате (JSON или путь к файлу). Все переменные, накопленные в схеме до момента запуска фонового процесса, сохраняются и доступны в следующей команде.

Обработка ошибок

Если запрос вернул HTTP-ошибку (4xx, 5xx) или истекло время ожидания в polling-режиме:

Переменная результата устанавливается в пустое значение.
Используйте блок «Условие» после API-запроса, чтобы проверить наличие результата и направить пользователя по нужной ветке.

Советы

Всегда добавляйте блок «Условие» после API-запроса для обработки случаев, когда сервер недоступен или вернул ошибку.
Храните токены API в переменных, а не в тексте URL — это упрощает обновление токенов.
Включайте кеширование для справочных данных (список категорий, курсы валют), чтобы не перегружать внешний API.