Права и роли

В отличие от Gateway Intents (грубая проверка «умеет ли бот вообще»), права из этого раздела определяют, что боту разрешено делать в конкретной группе и в конкретном канале. Система прав у ботов полностью совпадает с системой прав у людей — это одна и та же модель, как в Discord: биты прав (Permissions), роли, персональные и ролевые оверрайды на уровне канала/категории.

Управляемая роль бота

Когда владелец добавляет бота в группу (AddBotToGroup, см. «Быстрый старт»), сервер автоматически создаёт для бота отдельную управляемую роль («managed role») с набором битов прав, который владелец передал в поле permissions — это прямой аналог параметра permissions= в пригласительной ссылке Discord.

Важные особенности управляемой роли:

• владелец бота не может выдать боту больше прав, чем есть у него самого в этой группе;
• управляемую роль нельзя назначить/снять вручную через обычные методы работы с ролями — она привязана строго к одному боту;
• при исключении бота из группы или его выходе управляемая роль удаляется автоматически.

Дальше, уже находясь в группе, бот может (если ему выдан бит ManageRoles, см. ниже) создавать дополнительные, обычные роли и назначать их себе или другим участникам через методы BotsApi (CreateRole, AssignRole и т.д.) — они работают как самые обычные роли группы, без ограничений управляемой роли.

Как считаются эффективные права

Эффективные права участника (человека или бота) в конкретном канале считаются так же, как в Discord:

1. База — объединение (побитовое ИЛИ) прав роли @everyone и всех остальных ролей, назначенных участнику.
2. Если в базе есть бит Administrator — все дальнейшие проверки и оверрайды пропускаются, участник получает полный доступ.
3. Иначе последовательно применяются оверрайды канала (или родительской категории, если канал синхронизирован с ней): сначала оверрайд @everyone, затем объединённый deny/allow по всем остальным ролям участника (сначала снимаются все deny, затем добавляются все allow), и в конце — персональный оверрайд конкретного участника (имеет наивысший приоритет).

Если ваш бот получает отказ в действии, которое, казалось бы, разрешено его ролью — проверьте, нет ли на конкретном канале персонального «deny»-оверрайда для этого бота или его роли.

Список прав (Permissions)

Права — это битовая маска uint64. Значения битов стабильны и не меняются между версиями API.

Право	Значение бита (1 << n)	Описание
ViewChannels	1	Просматривать каналы группы
ManageChannels	2	Создавать, редактировать и удалять каналы и категории
ManageRoles	4	Создавать, редактировать, удалять роли; назначать/снимать роли участникам
ManageEmojisAndStickers	8	Управлять пользовательскими эмодзи и стикерами
ViewAuditLog	16	Просматривать журнал аудита группы
ViewServerInsights	32	Просматривать статистику и аналитику группы
ManageWebhooks	64	Управлять вебхуками
ManageServer	128	Изменять настройки группы
CreateInvite	256	Создавать пригласительные ссылки
ChangeNickname	512	Изменять собственный никнейм в группе
ManageNicknames	1024	Изменять никнеймы других участников
KickMembers	2048	Исключать участников из группы
BanMembers	4096	Блокировать участников в группе
ManageEvents	8192	Создавать и управлять событиями группы
Administrator	16384	Полные права без ограничений (см. алгоритм выше)
SendMessages	32768	Отправлять сообщения в текстовых каналах
SendMessagesInThreads	65536	Отправлять сообщения в тредах
CreatePublicThreads	131072	Создавать публичные треды
CreatePrivateThreads	262144	Создавать приватные треды
EmbedLinks	524288	Вставлять ссылки с предпросмотром в сообщениях
AttachFiles	1048576	Прикреплять файлы к сообщениям
AddReactions	2097152	Добавлять реакции на сообщения
UseExternalEmoji	4194304	Использовать эмодзи с других серверов
UseExternalStickers	8388608	Использовать стикеры с других серверов
MentionEveryone	16777216	Упоминать @everyone, @here и все роли
ManageMessages	33554432	Удалять и закреплять чужие сообщения
ManageThreads	67108864	Управлять тредами (архивировать, закреплять, удалять)
ReadMessageHistory	134217728	Просматривать историю сообщений канала
SendTextToSpeechMessages	268435456	Отправлять сообщения с озвучиванием текста (TTS)
UseApplicationCommands	536870912	Использовать слэш-команды приложений
Connect	1073741824	Подключаться к голосовому каналу
Speak	2147483648	Говорить в голосовом канале
Video	4294967296	Включать видео и демонстрацию экрана
StartActivities	8589934592	Запускать активности в голосовом канале
UseVoiceActivity	17179869184	Использовать голосовую активацию микрофона
PrioritySpeaker	34359738368	Приглушать звук других при собственной речи
MuteMembers	68719476736	Выключать микрофон другим участникам голосового канала
DeafenMembers	137438953472	Отключать звук другим участникам голосового канала
MoveMembers	274877906944	Перемещать участников между голосовыми каналами
RequestToSpeak	549755813888	Запрашивать право высказаться в трибунном канале

Для типичного текстового бота обычно достаточно ViewChannels | SendMessages | ReadMessageHistory | AddReactions = 1 | 32768 | 134217728 | 2097152 = 136314881.

Управление ролями и структурой группы от лица бота

Если у бота есть intent Guilds и в конкретной группе выданы соответствующие права (ManageChannels/ManageRoles), он может через BotsApi управлять структурой этой группы — точно теми же действиями, что доступны человеку с такими же правами:

Метод	Требуемое право (Permissions)	Что делает
CreateCategory	ManageChannels	Создаёт категорию в группе
CreateChannel	ManageChannels	Создаёт канал внутри категории
CreateRole	ManageRoles	Создаёт новую роль в группе
UpdateRole	ManageRoles	Изменяет имя/права/цвет роли
DeleteRole	ManageRoles	Удаляет роль
AssignRole	ManageRoles	Выдаёт роль участнику группы
RemoveRole	ManageRoles	Забирает роль у участника группы

Несколько правил, о которых важно помнить, если ваш бот работает с ролями:

• Иерархия ролей. Бот не может создать, изменить, выдать или забрать роль, которая находится выше или на одном уровне с его собственной управляемой ролью в иерархии позиций группы. Это то же правило, что действует для людей: нельзя управлять ролями «сильнее» собственной.
• Нельзя выдать больше прав, чем есть у себя. При создании роли с помощью CreateRole бот не может указать в правах новой роли биты, которых у него самого сейчас нет в этой группе (кроме случая, когда у самого бота уже есть Administrator).
• Создание группы («сервера») ботам недоступно намеренно. Бот может создавать только категории и каналы внутри уже существующей группы, в которой состоит — не саму группу.
• Роль @everyone и управляемые роли (в том числе принадлежащие другим ботам) нельзя изменять или удалять этими методами — сервер вернёт ошибку.

Полные описания запросов и ответов этих методов — в разделе «BotsApi: методы бота».