Группы

Раздел «Группы» — самый большой в API: создание и настройка групп, категории и каналы внутри группы, роли и права, приглашения, участники и журнал аудита. Права и модель их вычисления (роли, оверрайды, Administrator) полностью описаны в «Права и роли» — здесь эта модель не переобъясняется, только указано, какое право нужно для конкретного действия.

Все запросы этого раздела требуют заголовок Authorization: Bearer <accessToken>.

Объекты

Group / GroupDetails

Group — облегчённая проекция (используется в списках), GroupDetails — то же самое плюс categories и iAmIsOwner (возвращается только в «Получить группу»).

Поле	Тип	Описание
id	string	Идентификатор группы.
ownerId	string	Владелец группы.
name	string	Название группы.
accessType	AccessType	Тип доступа к группе.
verificationLevel	VerificationLevel	Уровень верификации участников.
createdAt	string	Когда группа создана (ISO8601).
avatarId / avatarUrl	string	Id и URL аватара группы.
bannerId / bannerUrl	string	Id и URL баннера группы.
isMuted	boolean	Отключены ли у текущего пользователя push-уведомления для этой группы — см. «Отключить уведомления».
categories	array	(только в GroupDetails) Категории группы, каждая — со своим списком каналов.
iAmIsOwner	boolean	(только в GroupDetails) Является ли текущий пользователь владельцем группы.

AccessType

Значение	Описание
OPEN	Открытая группа.
CLOSED	Закрытая группа.
INVITE_ONLY	Вход только по приглашению.
HIDDEN	Скрытая группа.

VerificationLevel

Значение	Описание
NONE	Без ограничений.
LOW	Низкий уровень верификации.
MEDIUM	Средний уровень верификации.

Category / Channel

Поле	Тип	Описание
Category.id / name / position	string	Идентификатор, название и позиция категории среди остальных категорий группы.
Category.channels	array	Каналы внутри категории.
Channel.id / name / position	string	Идентификатор, название и позиция канала среди остальных каналов категории.
Channel.type	integer	Тип канала (0 — текстовый, 1 — голосовой).
Channel.categoryId	string	Категория, которой принадлежит канал.
Channel.userLimit / bitrate	integer	Только для голосовых каналов.
Channel.isCategoryPermissionsSync	boolean	true (по умолчанию для новых каналов) — канал наследует оверрайды своей категории, собственные оверрайды канала при этом полностью игнорируются при резолвинге прав. false — канал живёт по собственным оверрайдам, категория на него не влияет. См. «Синхронизация прав канала с категорией».
Channel.users	array	Участники, подключённые к голосовому каналу прямо сейчас (см. «Каналы»).

Role

Поле	Тип	Описание
id	string	Идентификатор роли.
groupId	string	Группа, которой принадлежит роль.
name	string	Название роли.
position	string	Позиция роли в иерархии.
color	string	Цвет роли.
permissions	integer (int64)	Битовая маска прав роли — см. «Список прав».

Invite

Поле	Тип	Описание
id	string	Идентификатор приглашения.
groupId	string	Группа, в которую ведёт приглашение.
ownerId	string	Кто создал приглашение.
inviteCode	string	Код приглашения — то, что реально передаётся пользователю (например, в ссылке voice.gg/inviteCode).
createdAt	string	Когда приглашение создано (ISO8601).
expiresAt	string	Когда приглашение истекает (ISO8601); пусто, если бессрочное.
usesAmount	integer (int64)	Сколько раз приглашением уже воспользовались.
maxUseAmount	integer (int64)	Максимум использований; 0 — без ограничения.

GroupMember

Поле	Тип	Описание
user	User	Профиль участника.
roleIds	array<string>	Id ролей, назначенных участнику (без учёта неявной @everyone).

GroupAuditLogEntry

Поле	Тип	Описание
id	string	Идентификатор записи.
actorId / actorType / actorDisplayName	string	Кто выполнил действие (actorType различает пользователя и бота).
actionType	string	Тип действия (например, channel.update, role.delete).
targetId / targetDisplayName	string	На какую сущность подействовали.
changes	string	Описание изменений.
createdAt	string	Когда действие произошло (ISO8601).

Объект ошибки

При любой ошибке вместо 200 OK возвращается default-ответ:

Поле	Тип	Описание
code	integer	Числовой код ошибки (google.rpc.Code).
message	string	Человекочитаемое описание ошибки.
details	array	Дополнительные структурированные детали ошибки (google.protobuf.Any); в большинстве случаев пуст.

---

Группа

Создать группу

POST/v1/groups

Создаёт новую группу с текущим пользователем в роли владельца.

Тело запроса: name (string) — название группы.

Ответ 200 OK: id, ownerId, name, accessType, verificationLevel, createdAt.

Мои группы

GET/v1/groups

Возвращает список групп, в которых состоит текущий пользователь (облегчённая проекция Group, без категорий и каналов) — пользовательский аналог GetMyGroups из Bot API.

Ответ 200 OK: groups — массив объектов Group.

Получить группу

GET/v1/groups/{id}

Полная детализация одной группы: категории и каналы внутри неё.

Параметры пути: id — идентификатор группы.

Ответ 200 OK: group — объект GroupDetails.

Изменить группу

POST/v1/groups/{id}

Тело запроса: id, name?, description?, accessType?, verificationLevel?.

Требует ManageServer

Изменять настройки группы может владелец или участник с правом ManageServer.

Ответ 200 OK: обновлённый объект Group.

Удалить группу

POST/v1/groups/{id}:delete

Параметры пути: id — идентификатор группы.

Только владелец

Удалить группу может только её владелец. Действие необратимо.

Ответ 200 OK: id, success.

---

Участники

Список участников

GET/v1/groups/{groupId}/users

Параметры пути: groupId.

Ответ 200 OK: members — массив объектов GroupMember.

Исключить участника

POST/v1/groups/{groupId}/users/{userId}:kick

Параметры пути: groupId, userId — кого исключить.

Требует KickMembers

Ответ 200 OK: groupId, userId, success.

Покинуть группу

POST/v1/groups/{groupId}:leave

Параметры пути: groupId.

Владелец не может покинуть группу

Владельцу нужно сначала передать владение или удалить группу.

Ответ 200 OK: groupId, success.

Отключить уведомления

POST/v1/groups/{groupId}:mute

Включает или выключает push-уведомления текущего пользователя для группы — состояние личное, никак не влияет на остальных участников.

Параметры пути: groupId. Тело запроса: muted (boolean).

Ответ 200 OK: пустой объект {}.

Забанить участника

POST/v1/groups/{groupId}/users/{userId}:ban

Блокирует участника в группе — забаненный пользователь исключается из группы и не может вступить в неё повторно (в том числе по приглашению), пока бан не снят.

Параметры пути: groupId, userId — кого забанить. Тело запроса: reason? — причина бана.

Требует BanMembers

Действует та же проверка иерархии ролей, что и для исключения участника — нельзя забанить участника с ролью выше или равной своей.

Ответ 200 OK: groupId, userId, success.

Разбанить участника

POST/v1/groups/{groupId}/users/{userId}:unban

Параметры пути: groupId, userId.

Требует BanMembers

Ответ 200 OK: groupId, userId, success.

Список банов

GET/v1/groups/{groupId}/bans

Параметры пути: groupId.

Требует BanMembers

Ответ 200 OK: bans — массив объектов GroupBan: user (User), reason, bannedByUserId, bannedAt (ISO8601).

---

Роли

Список ролей

GET/v1/groups/{groupId}/roles

Список ролей группы, отсортированный по позиции (@everyone — всегда последняя) — то же самое, что GetGroupRoles в Bot API.

Параметры пути: groupId.

Ответ 200 OK: roles — массив объектов Role.

Создать роль

POST/v1/groups/{groupId}/roles

Тело запроса: groupId, name, color?, permissions?.

Требует ManageRoles

Создать роль с правами, которых нет у самого вызывающего, нельзя — так же, как и в управляемой роли бота.

Ответ 200 OK: созданный объект Role.

Изменить роль

POST/v1/groups/roles/{roleId}:update

Параметры пути: roleId. Тело запроса: name?, permissions?, color?.

Требует ManageRoles

Ответ 200 OK: обновлённый объект Role.

Переместить роль

POST/v1/groups/roles/{roleId}:move

Меняет позицию роли в иерархии.

Параметры пути: roleId. Тело запроса: previousRoleId?, nextRoleId? — роли, между которыми нужно вставить перемещаемую.

Ответ 200 OK: пустой объект {}.

Удалить роль

POST/v1/groups/roles/{roleId}:delete

Параметры пути: roleId.

Требует ManageRoles

Ответ 200 OK: id, success.

Назначить роль

POST/v1/groups/{groupId}/roles/{roleId}:assign

Параметры пути: groupId, roleId. Тело запроса: targetUserId — кому назначить роль.

Требует ManageRoles

Нельзя назначить роль с правами выше, чем у самого вызывающего.

Ответ 200 OK: пустой объект {}.

Снять роль

POST/v1/groups/{groupId}/roles/{roleId}:remove

Параметры пути: groupId, roleId. Тело запроса: targetUserId — у кого снять роль.

Требует ManageRoles

Ответ 200 OK: пустой объект {}.

---

Категории и каналы

Создать категорию

POST/v1/groups/{groupId}/categories

Параметры пути: groupId. Тело запроса: name.

Требует ManageChannels

Изменить категорию

POST/v1/groups/categories/{id}:update

Параметры пути: id. Тело запроса: name?.

Удалить категорию

POST/v1/groups/categories/{id}:delete

Параметры пути: id.

Требует ManageChannels

Удаление категории удаляет и все каналы внутри неё.

Ответ 200 OK: id, success.

Переместить категорию

POST/v1/groups/categories/{categoryId}:move

Параметры пути: categoryId. Тело запроса: previousCategoryId?, nextCategoryId?.

Создать канал

POST/v1/groups/{categoryId}/channels

Параметры пути: categoryId — категория, в которой создаётся канал. Тело запроса: name, type (0 — текстовый, 1 — голосовой).

Требует ManageChannels

Удалить канал

POST/v1/groups/channels/{id}:delete

Параметры пути: id.

Ответ 200 OK: id, success.

Переместить канал

POST/v1/groups/channels/{channelId}:move

Меняет позицию канала внутри категории либо переносит его в другую категорию.

Параметры пути: channelId. Тело запроса: previousChannelId?, nextChannelId?, targetCategoryId? — если нужно перенести канал в другую категорию.

Синхронизация прав канала с категорией

POST/v1/groups/channels/{channelId}:set-category-sync

Переключает isCategoryPermissionsSync канала (см. «Category / Channel»). Пока синхронизация включена, собственные оверрайды канала («Оверрайды канала») сохраняются на сервере, но полностью игнорируются при резолвинге эффективных прав — действуют только оверрайды категории.

Параметры пути: channelId. Тело запроса: isSynced (boolean).

Требует ManageChannels

Ответ 200 OK: обновлённый объект Channel.

---

Приглашения

Создать приглашение

POST/v1/groups/{groupId}/invites

Параметры пути: groupId. Тело запроса: expiresAt? (ISO8601, бессрочное — если не указано), maxUses? (без ограничения — если не указано или 0).

Требует CreateInvite

Ответ 200 OK: созданный объект Invite.

Список приглашений группы

GET/v1/groups/{groupId}/invites

Параметры пути: groupId.

Ответ 200 OK: invites — массив объектов Invite.

Изменить приглашение

POST/v1/groups/invites/{id}

Параметры пути: id. Тело запроса: expiresAt?, maxUses?.

Удалить приглашение

POST/v1/groups/invites/{id}:delete

Параметры пути: id.

Ответ 200 OK: пустой объект {}.

Вступить по приглашению

POST/v1/groups/join

Тело запроса: inviteCode — код приглашения.

Ответ 200 OK: groupId, success.

Ответ default (ошибка): стандартный объект ошибки — например, если код не найден, истёк, исчерпал лимит использований, либо пользователь уже состоит в группе.

---

Права доступа

Полные правила вычисления эффективных прав, битовые значения Permissions и разница между персональным и ролевым оверрайдом — в «Права и роли». Здесь — только эндпоинты для чтения и записи оверрайдов.

Эффективные права в канале

GET/v1/groups/{groupId}/permissions

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

Параметры пути: groupId.

Ответ 200 OK: permissions — integer (int64), битовая маска.

Оверрайды канала

GET/v1/groups/channels/{channelId}/permission-overwrites

Параметры пути: channelId.

Ответ 200 OK: overwrites — массив объектов ChannelPermissionOverwrite: targetId, isRoleTarget (роль или конкретный участник), allow, deny (битовые маски).

POST/v1/groups/channels/{channelId}/permission-overwrites:set

Создаёт или полностью заменяет оверрайд для указанной цели.

Параметры пути: channelId. Тело запроса: targetId, isRoleTarget, allow, deny.

Требует ManageChannels

POST/v1/groups/channels/{channelId}/permission-overwrites:delete

Параметры пути: channelId. Тело запроса: targetId, isRoleTarget.

Ответ 200 OK: пустой объект {} для обоих запросов.

Оверрайды категории

Аналогично оверрайдам канала, но применяются ко всем каналам категории, которые синхронизированы с ней (см. «Как считаются эффективные права»).

• GET/v1/groups/categories/{categoryId}/permission-overwrites
• POST/v1/groups/categories/{categoryId}/permission-overwrites:set
• POST/v1/groups/categories/{categoryId}/permission-overwrites:delete

Поля запросов и ответов идентичны эндпоинтам оверрайдов канала выше (categoryId вместо channelId).

---

Аудит-лог

GET/v1/groups/{groupId}/audit-log

Параметры пути: groupId.

Требует ViewAuditLog

Ответ 200 OK: entries — массив объектов GroupAuditLogEntry.

---

Аватар и баннер группы

Та же двухшаговая схема через предподписанный URL, что и у аватара пользователя и у вложений: сначала запрашивается URL загрузки, затем клиент грузит файл напрямую и подтверждает загрузку.

Аватар

POST/v1/groups/{groupId}/avatar/upload

Тело запроса: groupId, contentType, sizeBytes.

Ответ 200 OK: mediaId, uploadUrl, expiresAt.

POST/v1/groups/{groupId}/avatar/confirm

Тело запроса: groupId, avatarId (значение mediaId из предыдущего ответа).

Ответ 200 OK: обновлённый объект Group с новым avatarUrl.

Баннер

POST/v1/groups/{groupId}/banner/upload

Те же поля запроса/ответа, что у загрузки аватара.

POST/v1/groups/{groupId}/banner/confirm

Тело запроса: groupId, bannerId.

Ответ 200 OK: обновлённый объект Group с новым bannerUrl.

Требует ManageServer

Изменять аватар и баннер группы может владелец или участник с правом ManageServer.

Удалить аватар

DELETE/v1/groups/{groupId}/avatar

Параметры пути: groupId.

Ответ 200 OK: обновлённый объект Group с пустым avatarUrl.

Удалить баннер

DELETE/v1/groups/{groupId}/banner

Параметры пути: groupId.

Ответ 200 OK: обновлённый объект Group с пустым bannerUrl.

Требует ManageServer

Как и загрузка, удаление аватара и баннера доступно владельцу или участнику с правом ManageServer.