Элемент Запрос API в чат-ботах

Автоматизировать процесс стало еще проще с API запросами. C помощью этого функционала вы сможете, например по названию города сообщать погоду, по названию товара осуществлять поиск и выводить результат в чат-бот, по данным подписчика регистрировать его на мероприятие или создавать заказ.

Это работает так: вы отправляете запросы данных во внешние системы о любой информации, которой интересуется ваш пользователь или создаете новый объект. В ответ вы получаете данные, которые можно сразу выдавать в сообщении пользователю или записывать в переменную чат-бота.

Как отправить запрос на получение данных

Перетащите элемент Запрос API на рабочее поле, соедините его с элементом, после которого вам нужно получить информацию.

Выберите тип запроса:

• GET запрос обычно используют для получения уже существующих данных;
• POST запрос обычно используют для создания нового объекта в системе и получения информации о нем.

Введите URL, на который отправится запрос. В запросе можете использовать пользовательские и глобальные переменные вашего чат-бота и модифицировать их.

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

Если используете POST запрос, в нужном поле введите тело запроса в JSON с параметрами. Вы также можете модифицировать тело запроса.

Нажмите Проверить запрос для проверки отправки данных. Также проверка пригодится для распознавания данных при последующей настройке.

Как использовать полученные данные

В случае успешного запроса вы получите тело ответа, и пользователь пройдет по ветке Выполнено. Полученные данные можно использовать один раз в следующем текстовом блоке, записать в переменную чат-бота для многократного использования или отправить карточки сообщений на основе указанного массива.

По ветке Выполнено будут идти все ответы запросов со статусом 2хх. Ответы запросов с другими статусами пойдут по ветке Ошибка и данные нельзя будет использовать. Читайте подробнее: Как продолжить цепочку в случае ошибки запроса.

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

Использование данных с сохранением в переменную

Чтобы сохранить данные в переменные для дальнейшего использования, в элементе Запрос API перейдите во вкладку Сохранять значения и в настройках соответствий нажмите Добавить.

Из поля ответа выберите ключ, значение переменной которой вам нужно использовать.

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

Когда вы сохранили необходимое количество переменных, нажмите Применить и перейдите к созданию следующего блока.

В этом примере мы создали заказ, получили данные в ответ из нашей CRM, сохранили их в переменные и сообщаем пользователю для быстрой идентификации заказанной услуги или товара.

Пользователю общение с вашим чат-ботом выглядит вот так:

Использование данных в виде выражения JSON Path

Если вам не нужно записывать данные в переменные, можете использовать полученную информацию вставкой выражения пути JSON структуры.

Обратите внимание, что данные, которые вы не записываете, можно использовать только один раз в следующем текстовом блоке.

В тексте сообщения добавьте JSON Path {{$['somekey']['nestedkey']}}.

Чтобы использовать заголовки, cookies, статус-коды и другую системную информацию, полученную в результате запроса, укажите эти данные в виде {{$$['headers']}}, {{$$['cookies']}} или {{$$['data']}} в сообщении.

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

Пользователю общение с вашим чат-ботом этого примера выглядит вот так:

Чтобы использовать заголовки, cookies, статус-коды и другую системную информацию, полученную в результате запроса, укажите эти данные в виде {{$$['headers']}}, {{$$['cookies']}} или {{$$['data']}} в сообщении.

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

Использование для отправки карточки

На платном тарифе доступна также отправка карточек, сформированных из данных, которые будут получены в ответ на запрос. Для этого перейдите во вкладку Отправлять сообщения и заполните поля формы данными из полученного массива.

Читайте подробнее: Как отправлять карточки сообщений в чат-ботах.

Как продолжить цепочку в случае ошибки запроса

Разветвите сценарий и в случае неуспешного API запроса продолжить цепочку по ветке Ошибка. К примеру, вы можете сообщить об ошибке и переспросить необходимые данные, если они не совпадают, или позвать менеджера.

Вы также можете передать ответ сервера с ошибкой. Это помогает показывать пользователям сообщение об ошибке или записывать детали ошибки для отладки. Чтобы сослаться на конкретное поле в ответе с ошибкой, используйте выражение JSON Path, например {{$['status_code']}}.

Обновлено: 12.07.2024