Interactions

Interactions — Discord-style слэш-команды: команды с параметрами, которые бот регистрирует заранее, а пользователь вызывает через / в клиенте. Сюда же относится исполнение — вызов команды, клик по кнопке/меню на сообщении бота, сабмит модального окна и запрос автодополнения. Полностью жизненный цикл одного interaction'а (от вызова до ответа бота через RespondToInteraction) описан в «Interactions API: слэш-команды» — здесь только HTTP-контракт.

Раздел логически разбит на две части с разной аутентификацией:

Часть	Кто вызывает	Заголовок Authorization
Регистрация команд (RegisterCommand, UpdateCommand, DeleteCommand, GetBotCommands)	Владелец бота или сам бот	Bearer <accessToken> (владелец) либо Bot <botToken> с intent ApplicationCommands (сам бот)
Просмотр команд группы, исполнение (ExecuteCommand, RequestAutocomplete, InvokeMessageComponent, SubmitModal)	Любой участник группы	Bearer <accessToken> — это действие человека, не бота

Объект BotCommand

Поле	Тип	Описание
id	string	Идентификатор команды.
botId	string	Бот, которому принадлежит команда.
name	string	Название команды (то, что пользователь вводит после /).
description	string	Описание команды.
options	array	Параметры команды — объекты CommandOption.
defaultMemberPermissions	integer (int64)	Битовая маска Permissions — минимальные права, нужные участнику, чтобы видеть/вызывать команду.
createdAt / updatedAt	string	Когда команда создана/обновлена (ISO8601).

CommandOption

Поле	Тип	Описание
name	string	Название параметра.
description	string	Описание параметра.
type	CommandOptionType	Тип значения параметра.
required	boolean	Обязателен ли параметр.
choices	array	Статичный список допустимых значений — объекты { name, value }.
autocomplete	boolean	Если true, choices игнорируется — сервер вместо этого шлёт боту RequestAutocomplete по мере ввода.

CommandOptionType

STRING, INTEGER, BOOLEAN, USER, CHANNEL, ROLE, NUMBER, SUB_COMMAND, SUB_COMMAND_GROUP.

Объект InteractionResult

Возвращают все методы исполнения — результат ответа, который бот дал через RespondToInteraction.

Поле	Тип	Описание
type	string	Вид ответа: CHANNEL_MESSAGE, DEFERRED_CHANNEL_MESSAGE, UPDATE_MESSAGE, DEFERRED_UPDATE_MESSAGE, MODAL.
content	string	Текст сообщения (если применимо).
componentsJson	string	JSON ActionRow[] — компоненты на сообщении, см. «Компоненты и модальные окна».
modalJson	string	JSON модального окна (только для type: MODAL).
ephemeral	boolean	Виден ли ответ только вызвавшему команду пользователю.
messageId	string	Id созданного/обновлённого сообщения (если применимо).

Объект ошибки

При любой ошибке вместо 200 OK возвращается default-ответ:

Поле	Тип	Описание
code	integer	Числовой код ошибки (google.rpc.Code).
message	string	Человекочитаемое описание ошибки.
details	array	Дополнительные структурированные детали ошибки (google.protobuf.Any); в большинстве случаев пуст.

---

Регистрация команд

Зарегистрировать команду

POST/v1/interactions/bots/{botId}/commands

Параметры пути: botId. Тело запроса: name, description, options? (массив CommandOption), defaultMemberPermissions?.

Ответ 200 OK: созданный объект BotCommand.

Изменить команду

POST/v1/interactions/bots/{botId}/commands/{commandId}

Параметры пути: botId, commandId. Тело запроса: те же поля, что у регистрации.

Ответ 200 OK: обновлённый объект BotCommand.

Удалить команду

POST/v1/interactions/bots/{botId}/commands/{commandId}:delete

Параметры пути: botId, commandId.

Ответ 200 OK: пустой объект {}.

Команды бота

GET/v1/interactions/bots/{botId}/commands

Параметры пути: botId.

Ответ 200 OK: commands — массив объектов BotCommand.

Команды группы

GET/v1/interactions/groups/{groupId}/commands

Команды сразу всех ботов-участников группы за один вызов, вместо того чтобы перечислять участников группы и вызывать «Команды бота» для каждого. Доступен любому участнику группы — BotCommand.botId позволяет отличить, какому боту принадлежит каждая команда.

Параметры пути: groupId.

Ответ 200 OK: commands — массив объектов BotCommand.

Аутентификация — только владелец или сам бот

В отличие от «Команды группы», четыре метода выше (регистрация/изменение/удаление/ список команд конкретного бота) вызываются владельцем бота либо самим ботом — не произвольным участником группы.

---

Исполнение

Требуют Authorization: Bearer <accessToken> — это действие участника группы, не бота. Членство в группе и права на канал проверяются так же, как и для обычных сообщений (тот же SendMessages-чек).

Вызвать команду

POST/v1/interactions/bots/{botId}/commands/{commandId}:execute

Параметры пути: botId, commandId. Тело запроса: channelId, groupId?, options? — массив { name, value } со значениями введённых пользователем параметров.

Ответ 200 OK: объект InteractionResult.

Запросить автодополнение

POST/v1/interactions/bots/{botId}/commands/{commandId}:autocomplete

Вызывается по мере ввода пользователем текста в параметр с autocomplete: true.

Параметры пути: botId, commandId. Тело запроса: channelId, groupId?, focusedOption — какой параметр сейчас в фокусе, options? — уже введённые значения остальных параметров.

Ответ 200 OK: choices — массив { name, value }, динамически сформированный ботом.

Клик по компоненту сообщения

POST/v1/interactions/bots/{botId}/messages/{messageId}:invoke-component

Параметры пути: botId, messageId. Тело запроса: channelId, groupId?, customId — идентификатор кликнутого компонента (см. «Компоненты и модальные окна»), values? — выбранные значения (для select-меню с несколькими вариантами).

Ответ 200 OK: объект InteractionResult.

Отправить модальное окно

POST/v1/interactions/bots/{botId}/modals:submit

Параметры пути: botId. Тело запроса: channelId, groupId?, customId — идентификатор модального окна, fields? — массив { name, value } со значениями полей формы.

Ответ 200 OK: объект InteractionResult.

Ответ default (ошибка, для всех методов исполнения): стандартный объект ошибки — например, FAILED_PRECONDITION, если бот не успел ответить в отведённое окно времени (10 секунд для команд/компонентов/модалок, 3 секунды для автодополнения).