Права на канале

Что бот может делать, определяют два ограничения сразу:

что можно = права роли бота на канале  ∩  scope ключа

Роль — та же система ролей, что у обычных участников; её настраивает администратор канала. У бота нет «своих» прав поверх ролей: если роль не разрешает действие, API ответит 403.

Scope ключа выбираете вы при выпуске ключа. Он не добавляет возможностей — только сужает: ключ без messages:write не даст писать даже на канале, где роль это разрешает.

Ни одна сторона не может выдать больше, чем есть у другой. Поэтому утёкший ключ не даёт того, чего вы сами не просили, а администратор канала всегда может закрыть боту доступ, не спрашивая вас.

Роль по умолчанию

При установке на канал бот получает роль «Бот» с семью правами:

Право	Открывает	Нужный scope ключа
send_msg_text_room	отправку сообщений — POST /rooms/{id}/messages	messages:write
view_history_text_rooms	чтение истории — GET /rooms/{id}/messages	messages:read
edit_text_msg_you_own	правку своих сообщений — PATCH /rooms/{id}/messages/{id}	messages:write
delete_text_msg_you_own	удаление своих — DELETE /rooms/{id}/messages/{id}	messages:write
view_user_channel	список участников — GET /channels/{id}/members	channel:read
talk_voice_room	публикацию звука в голосовой	voice
mute_yourself_voice_room	управление своим микрофоном	voice

Для большинства ботов этого достаточно: писать, читать, видеть участников, говорить в голосовой.

Администратор видит этот же список на экране установки — и видит, до каких прав ваш ключ не дотягивается. Право, которым приложение не пользуется, помечено там отдельно, поэтому выпускать ключ «с запасом» смысла не имеет.

Если боту нужно больше

Попросите администратора канала сменить боту роль: настройки канала → Участники → бот → выбрать роль. Подойдёт любая существующая роль канала или специально созданная под бота.

Роль действует сразу — перезапускать бота не нужно.

Модерация

Маршруты модерации закрыты роли «Бот» полностью: ни одного из шести прав у неё нет и не будет. Это не недоработка — администратор канала должен выдать боту роль посильнее осознанно, тем же способом, каким повышает человека.

Право	Что открывает	Маршрут
pin_messages	закрепление сообщений	POST/DELETE /rooms/{id}/messages/{id}/pin
mute_users_chat_room	запрет писать в чат	PUT/DELETE /channels/{id}/members/{id}/chat-mute
mute_users_voice_room	мут микрофона	PUT/DELETE /channels/{id}/members/{id}/voice-mute
kick_users_voice_room	отключение от голосовой	DELETE /channels/{id}/members/{id}/voice
switch_users_in_room	перенос между комнатами	PUT /channels/{id}/members/{id}/room
kick_users_channel	исключение с канала	DELETE /channels/{id}/members/{id}

Всем шести нужен ещё и scope moderation у ключа.

Отказы модерации объясняют причину

В отличие от правки сообщений, эти маршруты возвращают в message текст от самого портала — например «Нельзя исключить владельца канала». Читайте его: он точнее, чем догадка по коду ответа.

Как выглядит нехватка права

Запрос отвечает 403:

{ "error": "Forbidden", "status": "error", "message": "Недостаточно прав" }

Сначала посмотрите на requiredScope

Если в теле 403 есть поле requiredScope — дело не в роли, а в ключе: вы не отметили этот доступ при выпуске. Лечится перевыпуском ключа, администратор канала тут ни при чём.

Права роли проверяются только после того, как запрос прошёл проверку ключа.

Частные случаи:

• Бот молчит в голосовой, хотя подключился. Посмотрите на canPublish в ответе входа в голосовую: false означает, что у роли нет talk_voice_room. Право проверяется на медиасервере, обойти его со стороны клиента нельзя.
• 403 на историю, но сообщения отправляются. Либо у ключа нет messages:read (тогда в ответе есть requiredScope), либо у роли нет view_history_text_rooms — так бывает у ролей, собранных вручную.
• Всё работало и вдруг перестало после перевыпуска ключа. При перевыпуске набор scope задаётся заново: проверьте, что отмечено всё, чем пользуется бот.

Текущую роль на каждом канале видно в ответе GET /me:

"channels": [
  { "id": "…", "name": "Тестовый сервак", "role": { "systemName": "CHANNEL_BOT", "name": "Бот" } }
]

Снятие с канала

Администратор может убрать приложение с канала в любой момент (настройки канала → Доступ → Приложения). После этого:

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

Сообщения, написанные ботом, остаются в истории канала.