Что такое Внешний Запрос

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

Например:

  • Выдать уникальный промокод.
  • Проверить информацию о бонусном балансе в программе лояльности.
  • Авторизовать пользователя с помощью его номера телефона.

Ответ от внешней системы можно обработать и сохранить в пользовательских полях для дальнейшего использования.

Возможности Внешнего Запроса

  • Широкие возможности настройки. Интеграция настраивается не с конкретной системой, а с REST API — не нужно писать отдельную интеграцию под каждую систему.
  • Персонализация. Возможность настроить запрос к внешнему сервису так, чтобы он учитывал уникальные данные каждого клиента. Например, бот может использовать конкретные данные: номер телефона или имя, чтобы получить информацию, актуальную именно для этого человека.
  • Обработка ошибок. Можно настроить, как бот будет реагировать, если что-то пошло не так. Например, если во внешнем запросе с авторизацией пользователя не удалось найти его номер во внешней системе.
  • Обогащение чата в TextBack данными из внешней системы. Внешний Запрос позволяет сохранять данные из внешней системы в поля чата. Например, можно сохранить имя пользователя и использовать его в дальнейшем диалоге.

Требования к API стороннего сервиса

  1. Поддержка REST API — способа обмена данными между клиентом и сервером с использованием стандартных HTTP-запросов.
  2. Формат JSON в запросах и ответах
  3. Максимальный размер ответа — 25 MB.

Пример JSON-запроса:

Настройка Внешнего Запроса

Настройка Внешнего Запроса состоит из двух основных этапов:

  1. Настройка запроса (что и как мы отправляем).
  2. Обработка ответа (что делать с данными, которые вернул API).

Зайдите в конструктор бота в личном кабинете TextBack, в разделе «Чат-боты».

Шаг 1: Добавьте блок с Внешним Запросом

  • В конструкторе чат-бота добавьте новый блок с действием «Внешний запрос». Внешний Запрос можно настраивать в блоке с другими действиями.

При клике на кнопку открывается окно с формой настройки Внешнего Запроса.

Шаг 2: Укажите основные параметры

  • Название. Это имя для идентификации запроса в чат-боте (например, «Получить промокод»). Оно не влияет на работу запроса. Может быть до 50 символов. В названии разрешаются любые символы: кириллица, латиница, цифры, знаки.

  • Метод. Выберите тип HTTP-запроса — GET (для получения данных) или POST (для отправки данных).

  • URL. Адрес ресурса, к котором обращается Внешний Запрос. Например:

Принимаются URL как с протоколом https, так и http — но протокол должен быть указан при вводе.

URL можно указывать вместе с query-параметрами — они автоматически заполнятся в секции «Параметры».

Шаг 3: Настройте Query-параметры

Query-параметры — это дополнительные данные, которые уточняют запрос. Они позволяют сделать метод более гибким и функциональным. Параметры добавляются в конец URL после знака вопроса (?), за которым следует пара «параметр-значение», между которыми расположен символ равно (=). Если параметров несколько, они разделяются символом амперсанд (&).

Параметры можно добавить:

  • Прямо в URL: тогда данные из ссылки подтянутся в «Параметры» автоматически.
  • Вручную в отдельной секции «Параметры», тогда данные из параметров подтянуться в URL.

Каждый параметр состоит из двух обязательных полей:

  1. Название, может содержать до 100 символов. 
  2. Значение, может содержать до 2000 символов.

Шаг 4: Настройте авторизацию

Большинство API требуют авторизации для работы. По умолчанию указано «No Auth», но можно также выбрать другие варианты. Если нужного вам типа нет в разделе «Авторизации», выберите «No Auth», а реальную авторизацию укажите в соответствии с документацией сервиса — либо в «Заголовке», либо в «Параметре».

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

  • Basic: указывается пара «логин:пароль», которая кодируется при отправке запроса и добавляется в заголовки.

  • API key: указывается пара «ключ:значение», которая при отправке добавляется или в параметры запроса, или в заголовки запроса.

  • Bearer key: указывается строка (JWT токен), которая при отправке добавляется в заголовки запроса с приставкой Bearer.

Шаг 5: Укажите заголовки

Заголовки — это дополнительные данные, которые передаются вместе с HTTP-запросом или ответом. Лимит: 50 заголовков.

Например, заголовки запроса в Mindbox:

  • Content-Type: application/json; charset=utf-8 (проставляется автоматически при выполнении Внешнего Запроса).
  • Accept: application/json (проставляется автоматически при выполнении Внешнего Запроса).

  • Authorization: SecretKey {Секретный ключ} (требуется указать вручную).

Шаг 6: Тело запроса (для POST)

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

Если JSON невалидный, то появится ошибка:

Тестирование Внешнего Запроса

Перед использованием можно протестировать запрос прямо в интерфейсе чат-бота:

Укажите тестовые значения для переменных (если они используются). Например, номер телефона в сценарии авторизации по номеру. Нажмите «Тестировать запрос».

Вы увидите:

  • Код ответа.
  • Время выполнения.
  • Размер ответа.
  • Тело ответа (данные, которые вернул API).
  • Заголовки ответа (технические данные).

Если ответ получен «200 ОК», то внешний запрос работает корректно.

Действия после выполнения Внешнего Запроса

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

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

Например, пользователь авторизуется через чат-бот в программе лояльности по номеру телефона. Если номер найден, чат-бот действует по одному сценарию. Если не найден, то включается другой сценарий.

Шаг 1: Запись ответов

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

  1. JSON-путь — адрес значения в полученном ответе. Необходимо знать модель ответа (можно получить из документации сервиса, с которым настраивается интеграция, или через «Тестирование») и правильно написать путь поля. В текущей версии с этим помогут сторонние инструменты — например https://jsonpathfinder.com/
  2. Поле — поле чата, в которое необходимо сохранить значение:
  • Для сохранения доступны как стандартные поля TextBack, так и пользовательские поля.
  • Новое поле можно создать прямо из интерфейса Внешнего Запроса.

  • Можно настроить параметр перезаписи для поля.
  • Можно настроить обязательность поля для сохранения ответа.

Важно! Запись произойдёт, если:

  1. Данные найдены по JSON-пути: необходимо проверять корректность JSON-пути.
  2. Каждому полю в TextBack присвоен 1 из 6 форматов (текст, число, телефон, email, дата, ссылка).

Если данные не соответствуют, Внешний Запрос пойдёт по сценарию «Неуспешный запрос». Для избежания ошибок можно снять флажок «Обязательно для записи».

Подробнее про пользовательские поля читайте в Базе Знаний TextBack

Шаг 2: Настройка повторов

Если запрос не удался (например, API вернул ошибку с кодом 5XX), можно настроить повторные попытки:

  • Количество повторов: от 1 до 5.
  • Интервал между повторами: от 1 до 60 секунд.

Как Внешний Запрос отображается в интерфейсе

Внешний запрос интегрирован в интерфейс чат-бота так же, как и другие действия. Он отображается в двух местах: в боковом меню и на диаграмме.

Боковое меню

После создания Внешнего Запроса в боковом меню появляется карточка с ключевой информацией:

  • Название действия: например, «Авторизация по номеру телефона».
  • Тип запроса: GET или POST.
  • Название запроса: то, что вы указали при настройке.
  • URL запроса: Адрес API. Если URL длинный, он обрезается, но при наведении курсора отображается полностью. URL можно скопировать.

В верхнем правом углу карточки находятся кнопки для редактирования и удаления.

Под карточкой находится блок, который объясняет, что произойдёт после выполнения запроса:

  • Если запрос успешен, бот перейдёт к следующему действию.
  • Если запрос неудачен, бот выполнит альтернативный сценарий (например, сообщит об ошибке).

Диаграмма

Диаграмма — это визуальное представление работы Внешнего Запроса в чат-боте.

На диаграмме блок Внешнего Запроса будет связан с двумя другими блоками:

  • Один блок для успешного сценария (например, при успешной авторизации по номеру телефона).
  • Другой блок для неудачного сценария (например, сообщение об ошибке).