Обратная связь - Отправка запроса API

Исходящая интеграция API: сообщение с обратной связью

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

Это не API для заполнения формы клиентом

Когда срабатывает

Пользователь ответил на все обязательные вопросы формы.
Статус заявки переводится в завершённый (finishAnswer).
Для каждой записи feedback_api, привязанной к этой форме, выполняется стратегия по типу интеграции.

Доступные типы интеграций (на момент документа):

`type` (api_type.id)	Название	Исходящее действие
`1`	Google Таблица	Запись строки через Google Sheets API
`3`	Свой API (Custom)	HTTP POST на URL владельца

HTTP-запрос

Параметр	Значение
Метод	`POST`
URL	Поле `public_key` в настройках интеграции (в ЛК — публичный ключ; фактически полный URL вашего webhook, например `https://api.bot-t.com/feedback/hook`)
Тело	`application/x-www-form-urlencoded` (Guzzle `form_params`)
Прокси	Системный прокси BOT-T (как в `ApiRequestService`) — при необходимости учитывайте на стороне firewall

Данные тела формируются из объекта FeedbackAnswerDto приведением (array) $answerDto — в POST попадают публичные scalar-поля верхнего уровня. Вложенные объекты (user, status, items, adminAnswer) в form-urlencoded не раскладываются в JSON; для интеграции ориентируйтесь прежде всего на:

Поле	Тип	Описание
`id`	int	ID заявки (ответа)
`feedback_id`	int	ID формы обратной связи
`answer`	string	Сводный текст заявки — все вопросы и ответы в читаемом виде
`created_time`	string	Время начала (`Y-m-d H:i`, часовой пояс бота)
`notice_time`	string\|null	Время напоминания
`deleted_time`	string	Время автоудаления заявки
`data`	string\|null	JSON-строка спец. данных (например `order_id` для форм доставки)
`bot_id`	int\|null	ID бота

Поле answer — основной источник для CRM/скриптов: там уже собран текст по всем полям формы.

Пример логики тела (упрощённо):

id=5001
&feedback_id=120
&answer=Вопрос%3A+Имя%0AОтвет%3A+Иван
&created_time=23-05-26+15%3A32
&deleted_time=24-05-26+15%3A32
&data=%7B%22order_id%22%3A%22123132%22%7D
&bot_id=42

Если нужна полная структура по каждому вопросу (items, файлы, select), её следует получать отдельно через API заявок ЛК (v1/bot/messagenew/feedback/answer/*) по id заявки — исходящий Custom webhook на это не рассчитан.

Ожидаемый ответ вашего сервера

Ответ должен быть HTTP 200 и JSON:

Успех:

{
  "result": true,
  "data": { }
}

Опциональные поля в data:

Поле	Тип	Поведение BOT-T
`message`	string	Текст отправляется пользователю в Telegram (`parse_mode: HTML`)
`is_repeat`	bool	Если `true` — заявка удаляется, пользователю снова отправляется стартовое сообщение формы (повторное заполнение)

Ошибка:

{
  "result": false,
  "message": "Описание ошибки"
}

При result: false или исключении текст из message (или текста ошибки) записывается в заявку как служебное сообщение (read), администратор видит ошибку в ЛК.

Валидация ответа: core/services/common/ApiRequestService.php (sendPostNew).

Тип «Google Таблица»

Реализация: core/services/common/ApiType/strategy/GoogleTableApiTypeStrategy.php.

Это не HTTP на ваш сервер, а запись в Google Sheets через официальный API.

Настройки в ЛК

Поле	Назначение
`public_key`	ID таблицы (spreadsheet id)
`private_key`	JSON service account (учётные данные Google)
`private_key_2`	Зарезервировано в форме обновления

Формат записи

При первой записи в диапазон A1:F выставляется строка заголовков:
ID:, FEEDBACK_ID:, ANSWER:, CLIENT_TELEGRAM_ID:, CLIENT_FIRST_NAME:, CLIENT_USERNAME:
Новая заявка добавляется в следующую свободную строку (колонки A–F):

Колонка	Значение
A	`id` заявки
B	`feedback_id`
C	`answer` (сводный текст)
D	`user.telegram_id`
E	`user.first_name`
F	`user.username`

Лимит: 1000 строк данных; при превышении запись пропускается, владельцу бота уходит уведомление в админ-панель.

Настройка интеграций через API ЛК

Базовый URL: v1/bot/messagenew/feedback/api/

Авторизация: как у остального API редактора (bot_id, token бота в query, тело JSON).

Основные методы

Action	Назначение
`index`	Список интеграций формы
`access`	Доступные типы для добавления
`count`	Количество интеграций
`create`	Создать (`message_id`, `type` = id api_type)
`update`	Обновить ключи (`id`, `public_key`, `private_key`, `private_key_2`)
`delete`	Удалить (`id` или массив `id`)

Ответ `index` / `create` / `update` — `FeedbackApiDto`

{
  "id": 10,
  "type": {
    "id": 3,
    "name": "Свой API",
    "image": "...",
    "description": "..."
  },
  "setting": {
    "id": 55,
    "public_key": "https://api.bot-t.com/hook",
    "private_key": "secret_or_json",
    "private_key_2": ""
  }
}

Для Custom в public_key указывается URL webhook, в private_key / private_key_2 — дополнительные секреты по необходимости (в Custom-стратегии в запросе используется только URL из public_key).

Полная структура заявки (справочно)

Если вы строите свой обработчик и забираете данные не только из form POST, полная модель заявки — FeedbackAnswerDto (api/modules/v1/dto/bot/message/feedback/answer/FeedbackAnswerDto.php):

Поле	Описание
`items[]`	Ответы по каждому вопросу (input / select / file / crossroad)
`user`	`UserDto`: `id`, `telegram_id`, `username`, `first_name`, `last_name`, `link`, `type`
`status`	`id`: 0 — в процессе, 1 — не прочитан, 2 — прочитан, 3 — отвечен; `title` — подпись
`adminAnswer`	Сообщение-ответ администратора (`MessageDto`), если есть

Типы вопросов в items[].type: INPUT = 1, FILE = 2, SELECT = 3, CROSSROAD

Схема завершения заявки

sequenceDiagram
    participant User as Пользователь
    participant Bot as BOT-T
    participant Hook as Ваш API / Google Sheets

    User->>Bot: Последний ответ формы
    Bot->>Bot: finishAnswer()
    loop Каждая интеграция feedback_api
        alt Custom (type=3)
            Bot->>Hook: POST form_params (FeedbackAnswerDto)
            Hook-->>Bot: JSON result/data
        else Google Table (type=1)
            Bot->>Hook: Google Sheets API append row
        end
    end
    Bot->>User: end_message (если настроено)