Внешний запрос

«Внешний запрос» можно найти в конструкторе ботов в блоке «Действие» в выпадающем списке действий.

Примеры сценариев использования «Внешнего запроса» в ботах

1. «Подписчик выбирает, какой он персонаж из фильма “Звёздные войны”»: ссылка.

Отправка запроса.
Тестирование запроса.
Описание простого JSON Path и запись данных из ответа в пользовательское поле.
Использование полученных данных в боте.

2. Интеграция с google-таблицами для считывания данных из таблицы: ссылка.

Настройка и подготовка google-аккаунта для интеграции.
Отправка и тестирование запроса.
Описание более сложного JSON Path и запись данных из ответа в пользовательское поле.
Использование полученных данных в боте.

3. Отправка СМС через сервис СМС Aero: ссылка на видео.

4. Генератор случайных чисел: ссылка.

5. Отправка уведомлений агенту в Telegram: ссылка.

6. Выдача сертификатов через сервис ГрамотаДел: ссылка на видео.

Общее описание

Действие «Внешний запрос» позволяет:

Отправлять запросы во внешние сервисы по их API. Доступные типы запросов:
- GET
- POST
- PUT
- PATCH
- DELETE
Записывать данные, полученные от внешнего сервиса в ответ на отправленный запрос, в пользовательские поля подписчиков.
В качестве теста отправить запрос и принять ответ внутри модального окна.
- Если для отправки запроса используются макросы, то при тестировании вместо них будут подставляться тестовые данные, значения которых можно изменить перед тестированием.

Все настройки «Внешнего запроса» выполняются в отдельном всплывающем (модальном) окне, которое открывается при редактировании.

Настройка и назначение всех элементов «Внешнего запроса» описаны ниже.

Тип запроса и URL-адрес

В выпадающем списке «Тип запроса» выберите тип отправляемого запроса. Его нужно искать в описании API сервиса, с которым настраивается взаимодействие.

В поле «URL-адрес» укажите адрес, на который будет отправляться запрос. Его тоже нужно искать в описании API сервиса.

При вводе URL-адреса допускается использование стандартных макросов (все макросы, которые есть в кабинете). Для того, чтобы подставить к ссылке макросы, нужно:

после самой ссылки поставить знак «?»;
при перечислении параметров соединить макросы знаком «&».

Пример: link.ru?utm_content=1&{%pole%}.

Раздел «Заголовки»

В этом разделе задаются заголовки для отправляемого запроса.

Вы можете:

добавлять/удалять заголовки;
использовать стандартные макросы в поле со значением «заголовок». При использовании макросов значение заголовка будет своё для каждого подписчика.

Раздел «Тело»

В этом разделе описывается тело запроса. Для этого раздела нужно взять код из настроек стороннего сервиса.

Тело должно быть описано в формате JSON.

При заполнении тела запроса допускается использование стандартных макросов.

В правой части «Предпросмотр» выполняются автоматическая валидация и форматирование введённого тела.

ВАЖНО! Этот раздел недоступен для запросов с типом GET.

Раздел «Ответ»

В этом разделе отображается ответ, который придёт от внешнего сервиса, когда запустится тестирование запроса.

Чтобы запустить тестирование запроса, нажмите на Отправить запрос или Протестировать запрос.

Если в заголовках, теле или URL-адресе используются макросы, то при тестировании вместо макросов будут подставлены тестовые значения. Вы можете изменить тестовые значения: для этого нужно раскрыть выпадающий список «Данные для тестирования» и изменить значение в поле «Тестовое значение» для нужного макроса.

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

Значения, полученные в теле ответа, можно сохранять в пользовательские поля подписчиков с помощью вкладки «Сопоставление ответов».

Раздел «Сопоставление ответов»

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

Данные и их структуру можно посмотреть, когда начнётся тестирование запроса, на вкладке «Ответ» в разделе «Тело ответа»:

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

Для настройки сопоставления нужно:

добавить правило сопоставления, нажав на кнопку + добавить сопоставление;
указать JSON Path — путь в теле ответа, по которому нужно забирать полученное значение. Подробная инструкция, как нужно писать JSON Path;
указать пользовательское поле, в которое будет сохраняться полученное в ответе значение.

ВАЖНО! После настройки и тестирования запроса обязательно нажмите Сохранить.

ВАЖНО! Чтобы настройки внешнего запроса не сбросились, обязательно сохраните шаг «Действие», в котором вы добавили внешний запрос.

Частые вопросы

Где взять Key для заголовков?

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

Примеры использования внешнего запроса

Автоматическая выдача именных сертификатов.

Видео на YouTube

Отправка SMS сообщений подписчикам.

Видео на YouTube

Уведомления в telegram-канале.

Видео на YouTube

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

Ниже рассмотрим самый простой сценарий того, как применять действие «Внешний запрос». Этот сценарий далёк от реального, но зато показывает все этапы настройки и функционал «Внешнего запроса».

Описание сценария и его настройка

В этом примере используем API сервиса swapi.dev. Сервис хранит в себе информацию о серии фильмов «Звёздные войны»: названия фильмов, имена персонажей и их характеристики, описания транспортных средств, планет, рас и так далее.

Другими словами, этот сервис — википедия по вселенной «Звёздные войны».

Основные этапы сценария

Подписчик попадает в бота.
Бот отправляет запрос в сервис swapi.dev с ID подписчика.
Сервис возвращает описание персонажа, у которого ID такой же, как у подписчика.
Бот записывает имя персонажа в пользовательское поле и выводит это значение подписчику.

Настройка бота

Соберите простую цепочку бота:

Добавьте блок «Сообщение 1».
- Напишите приветственный текст.
- Добавьте кнопку для перехода к следующему шагу.
Добавьте блок «Сообщение 2».
- Выведите пользователю его ID.
- По этому ID внешний сервис будет находить персонажа в своей базе.

Добавьте блок «Действие 1».
- В этом блоке выберите действие «Внешний запрос» (настройки внешнего запроса рассмотрим ниже).

Добавьте блок «Сообщение 3».
- Выведите пользовательское поле, в которое будете записывать имя персонажа, полученное от внешнего сервиса.
Соедините все блоки, и вы получите вот такого небольшого бота:

Настройка «Внешнего запроса»

Когда добавите действие «Внешний запрос» в блоке «Действие 1», кликните на «карандаш», чтобы открыть окно редактирования «Внешнего запроса». Дальше настраивать всё нужно в открывшемся окне.

Введите URL-адрес запроса.
- В описании сервиса swapi.dev выберите метод, который будет возвращать характеристики персонажа: https://swapi.dev/api/people/1/
- Скопируйте и вставьте адрес в поле «URL-адрес».
- В этом адресе «1» — ID персонажа. Вместо этого значения вставьте макрос, который будет автоматически подставлять внутренний ID подписчика. Для этого кликните на иконку <> в поле «URL-адрес» и выберите нужный макрос.
- Итоговая ссылка: https://swapi.dev/api/people/{%bh_user_id%}
Выберите тип запроса.
- Тип данного запроса — GET. Эта информация должна быть на сайте внешнего сервиса с описанием его API. Выберите GET в выпадающем списке «Тип запроса».

В данном методе не нужно заполнять заголовки или тело, поэтому перейдите к тестированию запроса.
- Чтобы перейти к тестированию запроса и убедиться, что всё работает правильно и сервис возвращает корректный ответ, перейдите на вкладку «Ответ» или кликните на кнопку Протестировать запрос.
- В открывшейся вкладке вы видите тестовые данные для используемых макросов. Значение по умолчанию: 10. При необходимости его можно изменить.
- Чтобы запустить тестирование, нажмите на кнопку Отправить запрос.
- В ответ приходит статус «200 ОК», значит, внешний сервис получил ваш запрос и успешно вернул ответ.
- В правой части окна в разделе «Тело ответа» можно посмотреть, что вы получили в ответ на запрос.
- Вам нужно значение поля “name”. Именно значение этого поля вы будете автоматически записывать в пользовательское поле подписчика.

Настройте сопоставление ответов.
- Сопоставление ответов позволяет настроить логику, которая из полученного тела ответа будет брать значение нужного поля и записывать его в указанное пользовательское поле подписчика.
- Для этого нужно указать путь, по которому требуется находить нужное поле в теле ответа (подробнее читайте тут), и само пользовательское поле, в которое нужно сохранять значение.
- Добавьте сопоставление и заполните появившиеся поля.
- Значение JSON Path “$.name” вернёт значение поля “name” из тела полученного ответа. В примере из тестирования было значение “Obi-Wan Kenobi”.

На этом настройка «Внешнего запроса» завершена.
- Обязательно сохраните его настройки кликом по кнопке Сохранить.
- Обязательно сохраните настройки открытого шага «Действие 1» кликом по кнопке Сохранить и закрыть.

Тестирование бота с внешним запросом

Запустите тестирование бота.
В итоге вы получите такую цепочку сообщений:

Я Дарт Вейдер, а кто вы? 🙂

Общее описание действия внешний запрос можно найти тут: ссылка.

Простой сценарий использования действия «Внешний запрос»

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

Ниже рассмотрим самый простой сценарий использования действия «Внешний запрос». Этот сценарий далёк от реального, но зато показывает этапы настройки и весь функционал «Внешнего запроса».