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

BotsApi — это self-service gRPC-сервис: каждый его метод вызывается от лица самого бота, токеном бота (см. «Аутентификация ботов»). Все методы, кроме GetMe, SetStatus, RespondToInteraction и SendInteractionFollowup, требуют соответствующий Gateway Intent, а реальные действия внутри группы дополнительно проверяются через права и роли.

Идентификаторы (bot_id, channel_id, group_id, role_id и т.д.) везде передаются как строки в формате GUID ("3fa85f64-5717-4562-b3fc-2c963f66afa6").

Профиль и статус

Метод	Intent	Описание
GetMe	—	Возвращает собственный профиль бота: id, username, display_name, аватар, статус, is_enabled, выданные intents.
SetStatus	—	Устанавливает статус присутствия бота (ONLINE / OFFLINE / DO_NOT_DISTURB / INVISIBLE) и опциональный текстовый статус. Изменение рассылается в реальном времени всем участникам групп бота (событие UserStatusChanged в group-events, см. «Gateway»).

Сообщения

Метод	Intent	Описание
SendMessage	GuildMessages	Отправляет сообщение в текстовый канал. Поля: channel_id, content, опционально reply_to (id сообщения, на которое отвечаем), attachment_ids (id уже загруженных вложений), components_json (кнопки/меню на сообщении, см. «Компоненты и модальные окна»).
UpdateMessage	GuildMessages	Редактирует ранее отправленное ботом сообщение (message_id, новый content, опционально новый components_json). Редактировать можно только собственные сообщения бота.
DeleteMessage	GuildMessages	Удаляет ранее отправленное ботом сообщение.
AddReaction / RemoveReaction	GuildMessages	Добавляет/убирает emoji-реакцию бота на сообщение (message_id, emoji).
Typing	GuildMessages	Индикатор «бот печатает» — простой булев флаг on/off, исчезает сам через несколько секунд, как в любом мессенджере.
SetTyping	GuildMessages	Более выразительный, «реактивный» индикатор состояния бота: THINKING, EXPLORED, PROCESSING, REVIEWED, OPENED, RE_SEARCH, FETCHED — удобно для ботов на основе LLM, которые хотят показать, что именно они сейчас делают (думают, читают файл, ищут в интернете и т.д.), а не просто «печатают». Гаснет сам, когда бот отправляет реальное сообщение в этот же канал, либо по таймауту на сервере — явного вызова «снять статус» нет.

Методы, возвращающие сообщение (SendMessage, UpdateMessage, AddReaction, RemoveReaction), отдают общий тип MessageInfo:

MessageInfo {
  id, channel_id, content, author_id
  created_at, updated_at
  is_edited, is_deleted
  reply_to
  reactions: map<emoji, { user_ids: [...] }>
  interaction_id, interaction_command_name, interaction_user_id   // если это ответ на interaction
  components_json                                                  // если к сообщению прикреплены компоненты
}

Голос

Метод	Intent	Описание
JoinVoiceChannel	GuildVoiceStates	Подключает бота к голосовому/медиа-каналу, возвращает token и server_url для подключения к медиасерверу (LiveKit).
LeaveVoiceChannel	GuildVoiceStates	Отключает бота от голосового канала.

Группы, каналы и роли

Метод	Intent	Описание
GetMyGroups	Guilds	Список групп, в которых состоит бот (облегчённая проекция, без категорий/каналов).
GetGroup	Guilds	Полная детализация одной группы: категории и каналы внутри неё.
GetGroupUsers	Guilds	Текущие участники группы (включая других ботов — с флагом is_bot = true).
GetGroupRoles	Guilds	Список ролей группы, отсортированный по позиции (@everyone — всегда последняя).
GetChannel	Guilds	Детали одного канала по его id — полезно, когда известен только channel_id (например, пришёл в событии Gateway), без похода за всей группой.
CreateCategory	Guilds	Создаёт категорию в группе (group_id, name). Требует право ManageChannels.
CreateChannel	Guilds	Создаёт канал внутри категории (category_id, name, type — 0 текстовый / 1 голосовой). Требует ManageChannels.
CreateRole	Guilds	Создаёт роль в группе (group_id, name, опционально color, список permissions). Требует ManageRoles.
UpdateRole	Guilds	Изменяет имя/права/цвет существующей роли. Требует ManageRoles.
DeleteRole	Guilds	Удаляет роль. Требует ManageRoles.
AssignRole	Guilds	Выдаёт роль участнику группы (group_id, target_user_id, role_id). Требует ManageRoles.
RemoveRole	Guilds	Забирает роль у участника группы. Требует ManageRoles.

Подробности про права, иерархию ролей и ограничения — в разделе «Права и роли».

Interactions (ответы на слэш-команды и компоненты)

Метод	Intent	Описание
RespondToInteraction	—	Отвечает на входящий interaction (слэш-команда, клик по кнопке/меню, сабмит модального окна или запрос автодополнения), полученный ботом через Gateway. Не требует intent — сервер сам проверяет, что отвечает именно тот бот, которому адресован interaction.
SendInteractionFollowup	—	Дополнительное сообщение уже после первого ответа на interaction (аналог Discord webhook followup) — доступно в пределах followup-окна.

Подробно про interactions — в отдельном разделе «Interactions API: слэш-команды».

Коды ошибок

Все методы BotsApi — обычный gRPC, ошибки возвращаются как стандартные gRPC-статусы:

Статус	Когда возникает
Unauthenticated	Токен отсутствует, синтаксически неверен или отозван
PermissionDenied	У бота нет нужного intent'а, либо не хватает права (Permissions) в конкретной группе/канале
InvalidArgument	Запрос не прошёл валидацию (например, channel_id — не валидный GUID)
NotFound	Сущность не найдена (или бот не имеет к ней доступа — по соображениям приватности сервер в части случаев намеренно возвращает NotFound вместо PermissionDenied, чтобы не подтверждать сам факт существования сущности)
FailedPrecondition	Действие невозможно в текущем состоянии (например, ответ на уже отвеченный или истёкший interaction)

Библиотеке стоит различать PermissionDenied из-за отсутствующего intent'а и PermissionDenied из-за отсутствующего права в группе — текст сообщения об ошибке в обоих случаях описывает причину явно, разбирайте его, если хотите показать разработчику бота точную подсказку.