Сообщение - API (Отправка запроса)

Исходящий HTTP-запрос: сообщение типа «API»

Документация описывает, какой запрос BOT-T отправляет на внешний сервер, когда в сценарии бота срабатывает свободное сообщение с типом API (MessageType::API, type_id = 14).

Настройка параметров выполняется в личном кабинете (раздел API сообщения) или через REST API редактора: префикс v1/bot/messagenew/api/*. Здесь описан только исходящий запрос к вашему endpoint.

Когда отправляется запрос

Запрос выполняется при прохождении сценария пользователем — в момент отправки сообщения типа API (очередь рассылки / цепочка свободных сообщений). Пользователю в Telegram ничего не показывается: выполняется только HTTP-вызов.

После ответа сервера BOT-T может поставить в очередь следующее сообщение сценария в зависимости от HTTP-кода (см. раздел «Ветвление по коду ответа»).

Общая схема

sequenceDiagram
    participant Bot as BOT-T
    participant API as Ваш API

    Bot->>Bot: Подстановка констант в params
    Bot->>API: HTTP method + host + headers/query/body
    API-->>Bot: HTTP status + body
    Bot->>Bot: Лог запроса
    alt 2xx и задан successMessageId
        Bot->>Bot: Очередь: следующее сообщение
    else 4xx и задан clientErrorMessageId
        Bot->>Bot: Очередь: сообщение ошибки клиента
    else 5xx и задан serverErrorMessageId
        Bot->>Bot: Очередь: сообщение ошибки сервера
    end

Параметры HTTP

Параметр в ЛК	Поле в БД	Описание
Хост API	`host`	Полный базовый URL endpoint (например `https://api.bot-t.com/v1/hook`). Используется как `base_uri` Guzzle; путь в запросе — пустая строка `''`, то есть вызывается именно этот URL без дополнительного суффикса.
Тип запроса	`type_request`	HTTP-метод: `POST` (по умолчанию), `GET`, `PUT`, `PATCH`, `DELETE`, `HEAD`.
Формат	`format`	Значение заголовка `Content-Type` (по умолчанию при создании: `Application/json`). Тело запроса всегда передаётся как JSON (`options['json']` в Guzzle), независимо от названия поля «формат».
Прокси	`proxy`	Опционально. Если задан — Guzzle использует этот прокси.

Дополнительно настраиваются три группы параметров (в ЛК — header / query / body):

`param_type`	Куда попадает
`header`	HTTP-заголовки (ключ и значение)
`query`	Query-string (`?key=value`)
`body`	JSON-тело запроса

Формирование тела (body)

Каждая запись body — пара param_key / param_value после подстановки констант.

Обычный ключ: поле верхнего уровня JSON, например user_id → "user_id": "1287634".
Ключ с точкой: вложенный объект. Ключ order.id даёт:

{
  "order": {
    "id": "12345"
  }
}

Если body пустой, опция json в запрос не добавляется (только headers и/или query).

Пример итогового запроса

Настройки:

host: https://api.bot-t.com/webhook
type_request: POST
format: application/json
header: Authorization = Bearer {TOKEN}
query: bot = {BOT_ID}
body: user_id = {USER_ID}, payload.message_id = {MESSAGE_ID}

Фактический вызов (логически):

POST https://api.bot-t.com/webhook?bot=42
Authorization: Bearer secret
Content-Type: application/json

{
  "user_id": "1287634",
  "payload": {
    "message_id": "9012"
  }
}

Подстановка констант

В param_key и param_value (все три типа: header, query, body) перед запросом выполняется замена плейсхолдеров {ИМЯ} через MessagesSpecTypeStrategy::replaceConstants() для текущего сообщения и пользователя.

Набор констант зависит от спецтипа (spec_type_id) сообщения. Базовый набор (свободное сообщение без спецтипа) включает:

Плейсхолдер	Описание
`{FIRST_NAME}`	Имя пользователя
`{SECOND_NAME}`	Фамилия
`{USER_TELEGRAM_ID}`	Telegram ID
`{USERNAME}`	@username
`{NAME}`	Имя-ссылка / ник
`{USER_ID}`	ID пользователя в боте
`{BALANCE}`	Баланс с валютой
`{BALANCE_WITHOUT_CURRENCY}`	Баланс без знака валюты
`{BOT_USER_CREATED_DATETIME}`	Дата регистрации в боте
`{MESSAGE_TITLE}`	Название сообщения в редакторе
`{MESSAGE_TYPE}`	Тип сообщения
`{MESSAGE_ID}`	ID сообщения
`{CURRENT_DATE}`	Дата в часовом поясе бота (ДД.ММ.ГГГГ)
`{CURRENT_TIME}`	Время (ЧЧ:ММ:СС)
`{CURRENT_DATETIME}`	Дата и время

Для спецтипов (магазин, подписка, профиль и т.д.) список расширяется — см. константы в редакторе сообщения или getConstants() соответствующей SpecType-стратегии.

В сценарий также могут передаваться дополнительные $params (например после предыдущих шагов); они участвуют в replaceConstants.

Ветвление по коду ответа

После запроса сохраняется лог (log_request_api: время, HTTP-код, тело ответа).

Диапазон кода	Поле в настройках	Действие
200–299	`success_message_id`	В очередь ставится отправка этого сообщения пользователю
400–499	`client_error_message_id`	Сообщение при клиентской ошибке
500+ или сеть без ответа	`server_error_message_id`	Сообщение при серверной ошибке

Если ID следующего сообщения для диапазона не задан, цепочка на этом шаге не продолжается.

При постановке следующего сообщения в $params добавляется ключ result — сырое тело HTTP-ответа (строка). Его можно использовать в константах следующих сообщений, если стратегия это поддерживает.

Требования к вашему API

URL — полный адрес в поле «Хост»; дополнительный path в коде не дописывается.
Метод — любой из перечисленных выше; для GET тело JSON обычно не отправляется (если body-параметры не заданы).
Ответ — BOT-T читает статус и тело; формат тела для ветвления сценария не парсится (важен только HTTP-код), кроме сохранения в result и лог.
Таймауты и SSL — стандартное поведение Guzzle HTTP-клиента.

Структура настроек в API редактора (справочно)

Объект messageApi в MessageDto:

{
  "id": 121234,
  "messageId": 121233,
  "host": "https://api.bot-t.com/webhook",
  "typeRequest": "POST",
  "format": "application/json",
  "proxy": null,
  "successMessageId": 121240,
  "clientErrorMessageId": 121241,
  "serverErrorMessageId": 121242,
  "paramsHeaders": [
    { "id": 1, "messageApiId": 121234, "paramType": "header", "paramKey": "Authorization", "paramValue": "Bearer token" }
  ],
  "paramsQuery": [],
  "paramsBody": [
    { "id": 2, "messageApiId": 121234, "paramType": "body", "paramKey": "user_id", "paramValue": "{USER_ID}" }
  ]
}