API обратной связи для пользователя бота

Документация для интеграции Telegram Web App, мобильного приложения или своего сайта: пользователь заполняет форму обратной связи от своего имени, без доступа к управлению ботом.

Логика совпадает с заполнением заявки в Telegram: те же вопросы, проверки и завершение.

Подробная спецификация полей доступна в интерактивной документации API вашей площадки (раздел «Обратная связь (пользователь)»).

Авторизация

Доступ к боту от имени владельца не нужен.

Все запросы отправляются методом POST в формате JSON.

Поля в каждом запросе

Поле	Описание
`bot_id`	Идентификатор бота в BOT-T.
`user_id`	Идентификатор пользователя в боте (не Telegram ID).
`secret_user_key`	Секретный ключ пользователя после регистрации или входа в боте.

Ключ и идентификатор пользователя выдаются при работе с API пользователей бота (например, после авторизации в Web App).

Ответ сервера

При успехе:

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

При ошибке:

{ "result": false, "message": "текст ошибки" }

Допустимо не более 120 запросов в минуту с одного IP-адреса.

Сценарий для Web App

get-active — проверить, есть ли незавершённый черновик; если active: true, продолжить с answer_id.
Если черновика нет — create (получить hello_text, первый вопрос и answer_id).
Отвечать на вопросы, пока completed: true.
При завершении показать end_text из ответа API.

list — история заявок пользователя по форме (без сохранения answer_id на клиенте).

sequenceDiagram
    participant App as Web App
    participant API as API обратной связи

    App->>API: get-active (message_id)
    alt active=true
        API-->>App: Текущий вопрос и answer_id
    else active=false
        App->>API: create
        API-->>App: hello_text, первый вопрос
    end
    loop Пока не completed
        App->>API: Ответ на вопрос
        API-->>App: Следующий вопрос
    end
    API-->>App: completed=true, end_text

Как заполнить заявку

Создайте заявку — получите hello_text, первый вопрос и answer_id (сохраните его).
Отвечайте на вопросы, пока в ответе не будет completed: true.
Завершение — покажите end_text; заявка уходит администрации бота.

Какой метод вызывать для ответа

Тип вопроса	Что делать
Текст	submit-input — отправить текст
Выбор одного варианта	submit-select — один раз с `option_id`; переход сразу
Выбор нескольких вариантов	submit-select — toggle (повторный `option_id` снимает выбор); затем select-confirm
Ветвление	submit-crossroad — выбрать ветку
Файл	submit-file или submit-file-data; при нескольких файлах — file-end

Мультивыбор (select)

Каждый вызов submit-select переключает вариант: выбран → снят, не выбран → выбран.
Текущий набор — в question.selected_option_ids (массив option_id).
После выбора вызовите select-confirm — переход к следующему вопросу.
Нужен хотя бы один выбранный вариант; иначе validation_error и тот же вопрос.
skip для необязательного мультивыбора (confirm: true) временно можно использовать вместо select-confirm — переход без выбора.

Дополнительные действия

Действие	Когда использовать
get-active	Восстановить черновик при открытии Web App
list	Список заявок пользователя по форме
continue	Снова получить текущий вопрос по `answer_id`
start	Начать заполнение заново
cancel	Отменить заявку
view	Посмотреть заявку целиком, в том числе ответ администратора

Данные в ответе при прохождении формы

Поле	Описание
`answer_id`	Номер заявки — нужен во всех следующих запросах
`completed`	`true` — форма заполнена
`hello_text`	Приветствие формы (только в ответе create)
`end_text`	Завершающий текст (при completed=true)
`validation_error`	Текст ошибки; тот же вопрос нужно отправить снова
`await_more_files`	`true` — можно приложить ещё файлы, затем file-end
`question`	Текущий вопрос (если форма ещё не завершена)
`answer`	Уже введённые ответы и служебная информация

Текущий вопрос (`question`)

Поле	Описание
`input_id`	Идентификатор вопроса для отправки ответа
`type`	`1` — текст, `2` — файл, `3` — выбор, `4` — ветвление
`text`	Текст вопроса
`confirm`	Вопрос необязательный — можно skip
`is_multiple`	Несколько вариантов или файлов
`selected_option_ids`	Выбранные `option_id` (для type=3, мультивыбор)
`options`	Варианты ответа (для выбора и ветвления)
`file.max_size`	Макс. размер файла в байтах (`0` — без ограничения)
`file.allowed_extensions`	Допустимые расширения/типы, например `["pdf","jpg"]`

Пример (create)

{
  "result": true,
  "data": {
    "answer_id": 100,
    "completed": false,
    "hello_text": "Заполните заявку — мы ответим в течение суток.",
    "end_text": null,
    "validation_error": null,
    "await_more_files": false,
    "question": {
      "input_id": 5,
      "type": 1,
      "text": "Ваш email?",
      "confirm": false,
      "is_multiple": false,
      "selected_option_ids": [],
      "options": [],
      "file": null
    },
    "answer": {}
  }
}

Пример (завершение)

{
  "result": true,
  "data": {
    "answer_id": 100,
    "completed": true,
    "hello_text": null,
    "end_text": "Спасибо! Мы свяжемся с вами.",
    "question": null,
    "answer": {}
  }
}

Список методов

Базовый адрес: /v1/bot/user/feedback/ (к вашему домену API).

Действие	Метод	Что передать дополнительно
Активный черновик	`get-active`	`message_id` формы
Список заявок	`list`	`message_id`; опционально `limit`, `offset`
Создать заявку	`create`	`message_id`; при необходимости — `data`
Начать заново	`start`	`answer_id`
Текущий вопрос	`continue`	`answer_id`
Просмотр заявки	`view`	`answer_id`
Ответ текстом	`submit-input`	`answer_id`, `input_id`, `text`
Переключить вариант	`submit-select`	`answer_id`, `input_id`, `option_id`
Подтвердить мультивыбор	`select-confirm`	`answer_id`, `input_id`
Ветвление	`submit-crossroad`	`answer_id`, `input_id`, `option_id`
Файл из Telegram	`submit-file`	`answer_id`, `input_id`, `file_id`, тип файла
Файл из приложения	`submit-file-data`	`answer_id`, `input_id`, имя и base64
Завершить загрузку файлов	`file-end`	`answer_id`, `input_id`
Пропустить вопрос	`skip`	`answer_id`, `input_id`, тип вопроса
Отменить заявку	`cancel`	`answer_id`

get-active

Поле в ответе	Описание
`active`	`false` — черновика нет
`active: true`	Остальные поля как в continue (`question`, `answer_id` и т.д.)

list

Поле в ответе	Описание
`items`	Массив заявок (новые первыми)
`total`	Общее количество
`limit`, `offset`	Параметры пагинации

Файл из Telegram (`submit-file`)

Тип (`file_kind`)	Описание
`photo`	Фото
`video`	Видео
`document`	Документ (укажите имя файла)
`sticker`	Стикер
`animation`	GIF / анимация

Файл из вашего приложения (`submit-file-data`)

Поле	Описание
`file_name`	Имя с расширением, например `report.pdf`
`file_data`	Содержимое файла в кодировке base64

Ограничения — в question.file: max_size, allowed_extensions.

Если разрешено несколько файлов: загрузите каждый отдельным запросом, затем file-end.

Пропуск вопроса (`skip`)

Доступен только для необязательных вопросов (confirm: true).

Web App и Telegram

В ответе create приходит hello_text — покажите его в интерфейсе вместо сообщения в чат.
При completed=true используйте end_text вместо финального сообщения бота.
После успешного заполнения бот может дополнительно отправить уведомление в Telegram — по настройкам формы.

Вывод средств через форму

Если в боте включён вывод баланса через обратную связь:

через API модуля можно инициировать вывод и диалог в Telegram;
для Web App создайте заявку методом create, указав форму вывода и при необходимости номер заявки на вывод в поле data.

Частые проблемы

Ситуация	Что проверить
Отказ в доступе	Верны ли `user_id` и `secret_user_key` для этого бота
Неверная форма	`message_id` должен относиться к форме обратной связи этого бота
Заявка уже закрыта	create или start; либо get-active для черновика
Мультивыбор не переходит дальше	Вызван ли select-confirm после submit-select
Пустой мультивыбор	Нужен хотя бы один элемент в `selected_option_ids`
Повтор по заказу	Для этого заказа заявка уже была отправлена