Scopes

Каждое действие требует конкретный scope, выданный владельцем при invite-в-Space.

Каталог

Чтение

Scope	Назначение
messages.read	Читать сообщения в allowed_channels
members.read	Видеть список членов Space
roles.read	Видеть роли

Запись

Scope	Назначение	Опасность
messages.send	Отправлять сообщения в allowed_channels	Средняя (impersonation)
messages.delete.own	Удалять собственные сообщения бота	Низкая
messages.react	Добавлять реакции	Низкая

Модерация

Эти scope'ы — высокая опасность. Запрашиваются только для moderation-ботов. Владелец Space выдаёт их явно при invite (consent screen — часть планируемого OAuth-flow, см. ниже).

Scope	Назначение
moderation.kick	Кикать участников
moderation.ban	Банить участников
moderation.mute	Mute участников
moderation.messages	Удалять чужие сообщения

Роли

Scope	Назначение
roles.assign	Назначать роли (не выше своей)

Voice

Scope	Назначение
voice.join	Заходить в voice-канал (аудио других не получает)
voice.publish_audio	Публиковать аудио (бот = «спикер»)

Команды

Scope	Назначение
commands	Доставка/видимость и инвокация slash-команд в Space (каталог канала, invoke, событие command.invoked). Регистрация набора команд (PUT /api/bot/commands) — глобальная, scope не требует. См. Команды.

События

Scope	Назначение
events.subscribe	Подписываться на дополнительные события (webhook)

Статус реализации. Работают: messages.read/send/react, messages.delete.own, moderation.messages, members.read, roles.read, moderation.kick, moderation.mute, voice.join, voice.publish_audio, commands. Пока НЕ реализованы (scope можно выдать, но эндпоинта ещё нет): moderation.ban, roles.assign, events.subscribe. Выдача скоупов — через invite админом Space; OAuth-consent — roadmap.

Implies (auto-include)

Некоторые scope'ы implies другие — нормализатор автоматически добавляет:

• voice.publish_audio → автоматически добавляется voice.join
• moderation.messages → автоматически добавляется messages.read
• roles.assign → автоматически добавляется roles.read
• moderation.kick → автоматически добавляется members.read
• moderation.ban → автоматически добавляется members.read
• moderation.mute → автоматически добавляется members.read

Что НЕ может бот (никаким scope'ом)

Эти права не существуют в платформе:

• voice.subscribe — получать аудио других участников. Hard rule на серверном уровне.
• messages.read.dm — читать DM. Изолировано физически.
• *.private — приватные каналы, куда бот не приглашён.
• Audit log других ботов — каждый владелец видит только своих.
• Modify Space settings — visibility / members / roles — доступно только владельцу Space.
• moderator на voice-комнатах — недоступно для bot-токенов.

Запрос scope'ов

Static-token bot

При invite через UI: владелец проставляет галки → membership записывается с scopes[]. При попытке вызова без scope — 403 + audit log.

OAuth-bot (planned)

OAuth-выдача скоупов ещё не реализована — см. OAuth2. Ниже — планируемый flow.

В authorize URL:

&scopes=messages.send,voice.join,voice.publish_audio

Пользователь видит consent screen со списком scope'ов человеческим языком. Может снять галки с некоторых (downscope), но не добавить.

Best practices

Минимум

/ping бот = только messages.send + messages.read. Не запрашивать moderation.* без необходимости.

Документировать

На странице бота для пользователей указать, зачем нужен каждый scope.

Прогрессивно

Опциональные фичи — request scope только при активации пользователем.

Per-channel

Владелец выбирает каналы — бот видит только их. См. Channels.