Gateway Intents
Gateway Intents — это грубая, категорийная проверка «умеет ли бот вообще трогать эту область функциональности» (сообщения, голос, структуру группы и т.д.). Это не то же самое, что права доступа внутри конкретной группы (за них отвечает система «Права и роли») — intents работают на уровне всего бота, одинаково для всех групп, в которых он состоит.
Если вы знакомы с Discord — это прямой аналог Discord Gateway Intents.
Зачем это нужно
Два независимых уровня проверки защищают от разных проблем:
- Intents — владелец бота осознанно решает, какими категориями возможностей боту вообще разрешено пользоваться, ещё до того, как бот попадёт в какую-либо группу. Например, бот, который должен только читать и отвечать на сообщения, не должен иметь возможности подключаться к голосовым каналам, даже если технически это описано в его коде.
- Permissions (роли) — то, что бот теперь имеет право «трогать сообщения» в принципе, ещё не значит, что он может отправлять сообщения в конкретном канале конкретной группы — это уже решает роль, выданная ему в этой группе.
По умолчанию (если явно не указано иное) у нового бота нет ни одного intent'а — он может
вызвать только GetMe (узнать свой профиль) и не получит вообще никаких событий через Gateway.
Список intents
Intents — это битовая маска (uint64), передаётся в поле intents при CreateBot/UpdateBot.
| Intent | Значение бита | Что открывает в BotsApi | Какие события Gateway включает |
|---|---|---|---|
Guilds | 1 | GetMyGroups, GetGroup, GetGroupUsers, GetChannel, GetGroupRoles, CreateCategory, CreateChannel, CreateRole, UpdateRole, DeleteRole, AssignRole, RemoveRole | group-events — вход/выход участников, изменения структуры группы (категории, каналы, роли), смена статуса присутствия |
GuildMessages | 2 | SendMessage, UpdateMessage, DeleteMessage, AddReaction, RemoveReaction, Typing, SetTyping | chat-events — новые/изменённые сообщения, реакции, индикаторы набора текста |
GuildVoiceStates | 4 | JoinVoiceChannel, LeaveVoiceChannel | channel-events — подключение/отключение участников голосового канала |
ApplicationCommands | 8 | Регистрация слэш-команд самим ботом через InteractionsApi (RegisterCommand/UpdateCommand/DeleteCommand/GetBotCommands) | — (не про доставку событий) |
Значения битов можно комбинировать обычным побитовым ИЛИ. Например, типичный бот, который читает
и отправляет сообщения и сам регистрирует свои слэш-команды при старте, запрашивает
Guilds | GuildMessages | ApplicationCommands = 1 | 2 | 8 = 11.
Чтобы не хардкодить значения битов в своей библиотеке/UI, можно запросить актуальный список
через владельческий метод GetAvailableIntents — он возвращает пары «имя intent'а → числовое
значение бита» и не привязан к конкретному боту.
Исключения — методы без intent
Несколько методов BotsApi не требуют intent вообще, потому что это действия бота над самим
собой, а не над чужим пространством группы/канала:
GetMe— получить собственный профиль;SetStatus— установить собственный статус присутствия (ONLINE/OFFLINE/DO_NOT_DISTURB/INVISIBLE);RespondToInteraction/SendInteractionFollowup— ответ на interaction, который и так адресован ровно этому боту (сервер сам проверяет владение конкретным interaction'ом, отдельная intent-проверка здесь избыточна).
Как это проверяется на практике
Если вы пишете свою библиотеку и вызываете метод, для которого у бота не выдан нужный intent,
gRPC-вызов завершится с ошибкой уровня PermissionDenied и сообщением о том, какого именно
intent'а не хватает. Такую ошибку стоит явно отличать от ошибки нехватки прав в конкретной группе
(Permissions, «Права и роли») — тексты ошибок разные, и
разработчику бота обычно нужно точно понимать, какую из двух вещей нужно донастроить: intent на
уровне самого бота или роль в конкретной группе.