Гильдии

Гильдия (в UI — «сервер») — коллекция пользователей, каналов и ролей. Бот всегда живёт в контексте конкретной гильдии: команды, XP, модерация — всё привязано к guild_id.

Объект Guild

Поля, которые бот реально использует:

{
  "id": "1424883034267582464",
  "name": "Test server",
  "icon": null,
  "banner": null,
  "owner_id": "974...",
  "roles": [ ... ],
  "emojis": [ ... ],
  "stickers": [ ... ],
  "features": [],
  "system_channel_id": "...",
  "member_count": 3,
  "channels": [ ... ]
}

Поле	Тип	Описание
`id`	snowflake	ID гильдии
`name`	string	Название (2-100 символов)
`icon`	string \| null	Hash иконки. URL: `https://floodilka.com/icons/<guild_id>/<icon>.png`
`banner`	string \| null	Hash баннера
`owner_id`	snowflake	Владелец (не может быть ботом)
`roles`	array of Role	Все роли гильдии
`emojis`	array	Кастомные эмоджи гильдии
`stickers`	array	Стикеры гильдии
`features`	array of string	Включённые фичи: `COMMUNITY`, `VERIFIED`, `PARTNERED` и т.п.
`system_channel_id`	snowflake \| null	Канал для системных сообщений (присоединения, левел-апы)
`member_count`	integer	Сколько участников
`channels`	array of Channel	Все каналы (в `GUILD_CREATE`, но не в REST-ответах)

Объект Role

{
  "id": "1424...",
  "name": "Модератор",
  "color": 3447003,
  "hoist": true,
  "position": 5,
  "permissions": "268435456",
  "managed": false,
  "mentionable": true
}

Поле	Тип	Описание
`id`	snowflake	ID роли
`name`	string	Имя
`color`	integer	RGB-цвет, `0` — без цвета
`hoist`	boolean	Отделять от остальных в списке участников
`position`	integer	Позиция в иерархии. Больше = выше
`permissions`	string	Битовая маска прав как строка (см. Права доступа)
`managed`	boolean	Управляется интеграцией — нельзя редактировать
`mentionable`	boolean	Можно упоминать через `@`

Объект Member

{
  "user": { ... },
  "nick": "Глав мод",
  "roles": ["1424...", "1424..."],
  "joined_at": "2026-04-01T12:00:00.000Z",
  "premium_since": null,
  "deaf": false,
  "mute": false,
  "pending": false,
  "communication_disabled_until": null
}

user — вложенный объект User
nick — ник в конкретной гильдии (null — используется user.global_name или user.username)
roles — массив ID ролей (не содержит @everyone)
communication_disabled_until — таймаут (ISO-время до которого участник не может писать; null — не в таймауте)
pending — участник ещё не прошёл member-screening

Эндпоинты

GET /guilds/:guild_id

Полный объект гильдии. Тяжёлый — не вызывайте в горячем пути.

GET /guilds/:guild_id/members

Список участников с пагинацией:

limit — 1-1000 (по умолчанию 1)
after — snowflake последнего полученного участника

Для большинства ботов проще полагаться на GUILD_CREATE + GUILD_MEMBER_ADD/UPDATE/REMOVE события из Gateway, чем дёргать этот эндпоинт.

GET /guilds/:guild_id/members/:user_id

Конкретный участник.

PATCH /guilds/:guild_id/members/:user_id

Изменить участника:

ник (MANAGE_NICKNAMES)
роли через поле roles (MANAGE_ROLES)
mute / deaf (MUTE_MEMBERS / DEAFEN_MEMBERS)
communication_disabled_until — timeout (MODERATE_MEMBERS)
channel_id — переместить в голосовой канал (MOVE_MEMBERS)

Пример timeout на 10 минут:

curl -X PATCH https://floodilka.com/api/v1/guilds/$GID/members/$UID \
  -H "Authorization: Bot $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"communication_disabled_until": "2026-04-23T23:00:00.000Z"}'

PUT /guilds/:guild_id/members/:user_id/roles/:role_id

DELETE /guilds/:guild_id/members/:user_id/roles/:role_id

Добавить / убрать одну роль без пересылки всего массива ролей. Требует MANAGE_ROLES + иерархию.

DELETE /guilds/:guild_id/members/:user_id

Кик. Требует KICK_MEMBERS.

PUT /guilds/:guild_id/bans/:user_id

Бан. Требует BAN_MEMBERS.

{ "delete_message_days": 7 }

delete_message_days (0-7) — удалить все сообщения забаненного за последние N дней.

GET /guilds/:guild_id/bans

DELETE /guilds/:guild_id/bans/:user_id

Список банов / снятие бана. Требуют BAN_MEMBERS.

POST /guilds/:guild_id/roles / PATCH / DELETE

CRUD для ролей. Требует MANAGE_ROLES.

GET /guilds/:guild_id/audit-logs

Журнал аудита — подробнее.

Что дальше

Каналы — каналы внутри гильдий
Сообщения — как писать в канал гильдии
События — GUILD_MEMBER_ADD, GUILD_ROLE_UPDATE и прочее
Журнал аудита — как читать лог модераторских действий