Desenvolvimento

Gerenciamento de servidores e canais

Cargos, hierarquia, permissões de canal e moderação de voz pelo bot, com a API REST.

Bots agem sobre servidores e canais pela API REST. As tabelas completas de rotas ficam na Referência REST; esta página explica as regras que valem para elas. Nas rotas de servidor, :g é o id do servidor e :c o id do canal, que você recebe no gateway (GUILD_CREATE, MESSAGE_CREATE) ou em GET /bot/guilds e GET /guilds/:g.

Canais de texto e de voz#

Canais de voz também carregam um chat de texto: bots leem e enviam mensagens neles pelas mesmas rotas e com as mesmas permissões dos canais de texto (VIEW_CHANNEL, READ_MESSAGE_HISTORY, SEND_MESSAGES), e recebem MESSAGE_CREATE e os demais eventos de mensagem se enxergarem o canal. Se o seu bot assume que todo evento de mensagem vem de um canal de texto, confira o campo type do canal (text ou voice). Categorias não têm mensagens.

Hierarquia de cargos#

A hierarquia vale para bots como para pessoas: o bot só mexe em cargos e membros abaixo do seu cargo mais alto, e o cargo gerenciado nasce abaixo de quem o adicionou. Rotas de gerenciamento do servidor (PATCH /guilds/:g etc.) exigem MANAGE_GUILD e seguem as mesmas regras de qualquer membro.

Para listar membros e cargos, use GET /guilds/:g (campos members e roles) ou os dados do GUILD_CREATE no gateway.

Permissões de canal (overwrites)#

PUT /guilds/:g/channels/:c/overwrites define as permissões de cargos e membros em um canal e exige MANAGE_ROLES. Como no Discord, a hierarquia de cargos não limita as permissões do canal: o bot pode definir as de qualquer cargo ou membro. A única regra é que o bot não pode liberar (allow) uma permissão que ele mesmo não tem.

Gerenciar cargos pelo bot#

O bot lê cargos e membros em GET /guilds/:g (campos roles e members, cada membro com roleIds) ou nos dados do GUILD_CREATE. O gateway não avisa quando cargos ou os cargos de alguém mudam, então releia antes de decidir. Para dar um cargo:

Bash

curl -s -X PATCH $API/guilds/$G/members/$ACCOUNT_ID -H "Authorization: Bot $TOKEN" -H "Content-Type: application/json" \
  -d '{"roleIds":["ID_DO_CARGO_ATUAL","ID_DO_CARGO_NOVO"]}'

roleIds substitui a lista inteira. Leia os cargos atuais do membro e envie a união (atuais mais o novo), senão os outros cargos são removidos.
O bot precisa de MANAGE_ROLES e só pode dar ou tirar cargos abaixo do cargo mais alto dele. Sem isso a API responde 403 ("Você só pode dar ou tirar cargos abaixo do seu."). Coloque o cargo gerenciado do bot acima do cargo que ele vai entregar (Configurações do servidor, Cargos).
A lista é guardada sem repetições, então enviar de novo um cargo que a pessoa já tem não duplica nada.

Moderação de voz#

POST /guilds/:g/members/:accountId/voice aplica uma ação a um membro que está em um canal de voz. O corpo é { "action": "mute" }, com uma destas ações:

Ação	O que faz	Permissão do bot
`mute`	Silencia o microfone da pessoa no servidor	`MUTE_MEMBERS`
`unmute`	Remove o silêncio	`MUTE_MEMBERS`
`deafen`	Ensurdece: a pessoa também é silenciada e não ouve ninguém até receber `undeafen`	`MUTE_MEMBERS`
`undeafen`	Remove o ensurdecimento	`MUTE_MEMBERS`
`disconnect`	Desconecta a pessoa do canal de voz	`MOVE_MEMBERS`

Só vale para quem tem cargo abaixo do bot. A voz do participante traz serverMuted e serverDeafened. Quem é desconectado por um moderador ou bot faz o bot de voz receber VOICE_LEFT com reason: "disconnected" (veja Voz).

Bash

curl -s -X POST $API/guilds/$G/members/$ACCOUNT_ID/voice \
  -H "Authorization: Bot $TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"mute"}'