Cargos e permissões

Uma permissão concede a um membro uma capacidade em um servidor, como enviar uma mensagem ou banir outro membro. Um cargo tem um conjunto delas como máscara de 64 bits sem sinal, e uma substituição de permissão armazenada em um canal ajusta esse conjunto para aquele canal.

Apenas Listar cargos do servidor aceita credencial bearer OAuth2, e toda outra rota aqui a rejeita com 403 ACCESS_DENIED. Um servidor com UNAVAILABLE_FOR_EVERYONE rejeita uma requisição autenticada com 403 MISSING_ACCESS, e UNAVAILABLE_FOR_EVERYONE_BUT_STAFF faz o mesmo para uma conta sem o flag de staff da instância.

O Decoding Chat resolve o servidor antes de qualquer cargo. Um servidor que não existe retorna 404 UNKNOWN_GUILD. Quando o servidor existe e o chamador não é membro, a requisição retorna 403 MISSING_PERMISSIONS, portanto a existência do servidor é visível a qualquer chamador autenticado. Toda rota que nomeia um cargo afirma MANAGE_ROLES antes de ler o cargo. Um chamador sem a permissão recebe 403 MISSING_PERMISSIONS mesmo para um cargo que não existe.

Permissões

Cada bit que o Decoding Chat define aparece abaixo.

Valor	Nome	Descrição
1 << 0	CREATE_INSTANT_INVITE	Criar um convite para um canal do servidor
1 << 1	KICK_MEMBERS	Remover um membro do servidor
1 << 2	BAN_MEMBERS	Criar e revogar um banimento do servidor
1 << 3	ADMINISTRATOR1	Ter todas as permissões e contornar qualquer substituição de permissão de canal
1 << 4	MANAGE_CHANNELS	Criar, modificar, reordenar e excluir canais do servidor
1 << 5	MANAGE_GUILD	Modificar configurações do servidor e gerenciar recursos de nível de servidor como convites, URL personalizada e descoberta
1 << 6	ADD_REACTIONS	Adicionar uma reação a uma mensagem em um canal do servidor
1 << 7	VIEW_AUDIT_LOG	Ler o log de auditoria do servidor
1 << 8	PRIORITY_SPEAKER	Usar voz prioritária em um canal de voz do servidor, avaliado pelo cliente
1 << 9	STREAM2	Publicar uma trilha de compartilhamento de tela em uma conexão de voz do servidor
1 << 10	VIEW_CHANNEL3	Visualizar um canal do servidor
1 << 11	SEND_MESSAGES	Enviar uma mensagem em um canal de texto ou de voz do servidor
1 << 12	SEND_TTS_MESSAGES	Enviar uma mensagem que solicita reprodução text-to-speech
1 << 13	MANAGE_MESSAGES4	Excluir a mensagem de outro membro, excluir mensagens em massa, remover a reação de outro membro e editar os flags e anexos da mensagem de outro membro
1 << 14	EMBED_LINKS	Ter um link na própria mensagem do chamador expandido em um embed
1 << 15	ATTACH_FILES	Anexar um arquivo a uma mensagem
1 << 16	READ_MESSAGE_HISTORY	Ler mensagens enviadas antes do message_history_cutoff do servidor, ou qualquer mensagem quando o servidor não tem corte
1 << 17	MENTION_EVERYONE	Usar as menções everyone e here em um canal do servidor
1 << 18	USE_EXTERNAL_EMOJIS	Usar um emoji de outro servidor em uma mensagem ou reação
1 << 20	CONNECT	Conectar-se a um canal de voz do servidor
1 << 21	SPEAK	Transmitir áudio em um canal de voz do servidor
1 << 22	MUTE_MEMBERS	Aplicar e remover mute de moderador em um canal de voz do servidor
1 << 23	DEAFEN_MEMBERS	Aplicar e remover deaf de moderador em um canal de voz do servidor
1 << 24	MOVE_MEMBERS	Mover um membro entre canais de voz do servidor ou desconectar um membro
1 << 25	USE_VAD	Usar detecção de atividade de voz em vez de push-to-talk em um canal de voz do servidor, avaliado pelo cliente
1 << 26	CHANGE_NICKNAME	Alterar o próprio apelido do chamador no servidor
1 << 27	MANAGE_NICKNAMES	Alterar o apelido de outro membro no servidor
1 << 28	MANAGE_ROLES5	Criar, modificar, posicionar e excluir cargos, atribuir cargo a membro e definir substituição de permissão de canal
1 << 29	MANAGE_WEBHOOKS	Criar, modificar e excluir webhook em um canal do servidor
1 << 30	MANAGE_EXPRESSIONS6	Modificar e excluir emoji ou sticker criado por outro membro
1 << 37	USE_EXTERNAL_STICKERS	Usar um sticker de outro servidor
1 << 40	MODERATE_MEMBERS	Aplicar e remover timeout de comunicação de membro
1 << 43	CREATE_EXPRESSIONS6	Criar emoji ou sticker, e modificar ou excluir os que o chamador criou
1 << 51	PIN_MESSAGES	Fixar e desafixar mensagem em canal do servidor
1 << 52	BYPASS_SLOWMODE	Enviar mensagem sem aguardar o intervalo de modo lento do canal
1 << 53	UPDATE_RTC_REGION	Alterar a região de voz de um canal de voz do servidor
1 << 54	VIEW_CHANNEL_MEMBERS7	Visualizar a lista de membros de um canal do servidor

¹ Um membro que detém o bit por qualquer cargo atribuído recebe a máscara completa de 64 bits, e o Decoding Chat não aplica nenhuma substituição de canal depois

² O mesmo bit controla a trilha de câmera, portanto um membro sem ele não publica nem compartilhamento de tela nem vídeo

³ O Decoding Chat também trata uma categoria como visível quando pelo menos um canal dentro dela é visível

⁴ Excluir ou editar a própria mensagem do chamador não requer o bit

⁵ Uma mutação de cargo também requer autoridade de hierarquia sobre o cargo-alvo

⁶ Modificar ou excluir uma expressão criada pelo chamador requer CREATE_EXPRESSIONS, e a mesma operação em uma expressão criada por outro membro requer MANAGE_EXPRESSIONS

⁷ O bit é controlado por feature na escrita, portanto uma requisição que não declara a feature não pode alterá-lo

Os bits 19, 31 a 36, 38, 39, 41, 42, 44 a 50 e 55 a 63 não estão atribuídos.

STREAM autoriza uma trilha na conexão existente

A trilha é um compartilhamento de tela ou câmera. O Decoding Chat não abre uma segunda conexão para ela, e perder o bit silencia as trilhas publicadas enquanto a conexão de voz permanece ativa.

Máscaras de permissão são strings decimais no protocolo

Todo campo de permissão em resposta usa a representação decimal de um inteiro sem sinal de 64 bits dentro de uma string JSON. Um campo de permissão em requisição aceita aquela string decimal ou um número JSON que é um inteiro seguro, e o valor é um inteiro não negativo não maior que 9223372036854775807.

Um valor que não é uma sequência de dígitos decimais é rejeitado com o código de validação INVALID_INTEGER_FORMAT, e um acima do máximo com INTEGER_OUT_OF_INT64_RANGE. Um número JSON não pode representar o intervalo completo de 64 bits, portanto um cliente DEVE analisar e combinar máscaras com aritmética de inteiros sem sinal de 64 bits e NÃO DEVE compará-las com igualdade de string.

O Decoding Chat descarta um bit que não define. Uma mutação de cargo intersecciona a máscara solicitada com o conjunto de bits definidos antes da autorização. Um bit não atribuído nunca aparece em uma resposta. Uma substituição de permissão de canal usa a mesma máscara e o mesmo conjunto de bits definidos. O Decoding Chat não filtra bits por tipo de canal, portanto uma substituição pode nomear uma permissão que seu canal não usa.

Bits de permissão controlados por feature

O Decoding Chat controla alguns bits de permissão por uma declaração de feature, que um cliente envia no cabeçalho de requisição X-Fluxer-Features como lista separada por vírgulas.

Um bit é controlado hoje. VIEW_CHANNEL_MEMBERS requer o nome de feature view_channel_members_permission.

Em uma escrita de cargo ou substituição que não declare a feature correspondente, o Decoding Chat mantém o bit controlado em seu valor armazenado, portanto a requisição não pode nem definir nem limpar esse bit. Todos os outros bits na mesma máscara são escritos normalmente.

O Decoding Chat apara e converte em minúsculas cada nome no cabeçalho antes de compará-lo. Um nome vazio, com mais de 64 caracteres ou contendo caractere fora de a-z, 0-9 e _ é ignorado. O Decoding Chat lê no máximo 64 nomes de um cabeçalho. Um cabeçalho ausente ou vazio não declara nenhuma feature.

Em Criar cargo no servidor, uma requisição que fornece permissions sem declarar a feature sempre cria o cargo com VIEW_CHANNEL_MEMBERS limpo. Uma requisição que omite permissions copia a máscara do cargo everyone sem aplicar o gate.

Permissões elevadas

KICK_MEMBERS, BAN_MEMBERS, ADMINISTRATOR, MANAGE_CHANNELS, MANAGE_GUILD, MANAGE_MESSAGES, MANAGE_ROLES, MANAGE_WEBHOOKS e MODERATE_MEMBERS são permissões elevadas. Em um servidor cujo nível de MFA é elevado, apenas o dono do servidor as usa sem um autenticador registrado.

Uma operação que afirma uma permissão elevada que o chamador possui mas não pode usar retorna 400 TWO_FACTOR_REQUIRED. A verificação ocorre depois que o Decoding Chat confirmou a própria permissão, portanto um chamador que não tem a permissão recebe 403 MISSING_PERMISSIONS.

Listar cargos do servidor não afirma nenhuma permissão, portanto nunca produz TWO_FACTOR_REQUIRED.

A máscara reportada mantém todos os bits elevados

O requisito de MFA bloqueia a operação e deixa a máscara inalterada. Um campo permissions reporta o que os cargos do chamador concedem, portanto um cliente que oculta uma ação deve comparar o nível de MFA do servidor com seu próprio estado de registro.

Cálculo de permissões

O Decoding Chat calcula um conjunto de permissões para um membro em um servidor e, opcionalmente, em um canal daquele servidor. O resultado é a máscara efetiva completa para aquele membro naquele momento.

O dono do servidor recebe a máscara completa de 64 bits. Um usuário que não é membro recebe máscara vazia.

Caso contrário, o Decoding Chat começa pelas permissões do cargo everyone, cujo snowflake é igual ao snowflake do servidor, e então adiciona as permissões de cada cargo atribuído ao membro com uma união bit a bit. Se o resultado contiver ADMINISTRATOR nesse ponto, o Decoding Chat retorna a máscara completa de 64 bits e não executa mais nenhuma etapa.

Quando nenhum canal foi nomeado, a união é o resultado final. Quando um canal foi nomeado, o Decoding Chat aplica as substituições de permissão armazenadas naquele canal à união nesta ordem:

1. A substituição do cargo everyone, removendo seus bits negados e depois adicionando seus bits permitidos.
2. As substituições que têm como alvo cargos atribuídos ao membro, combinadas em uma união de bits permitidos e uma união de bits negados e aplicadas como etapa única na mesma ordem. Um allow em qualquer um dos cargos do membro vence um deny em outro.
3. A substituição do membro, novamente bits negados primeiro e bits permitidos depois.

Quando o canal nomeado não existe no servidor, o Decoding Chat deixa a união em nível de servidor inalterada.

ADMINISTRATOR concede todos os bits e ignora substituições

Nenhuma substituição deny em qualquer canal restringe um membro que possui o bit. Remover ADMINISTRATOR de cada cargo que ele possui é a única solução.

Um canal do servidor é visível quando sua máscara com escopo de canal contém VIEW_CHANNEL, ou quando o membro tem acesso temporário por uma transição de voz ou chamada em andamento. Uma categoria também é visível quando a máscara de pelo menos um canal filho contém VIEW_CHANNEL. O acesso temporário aplica-se apenas ao canal em que foi concedido.

Timeout de comunicação

Um timeout de comunicação impede um membro de se comunicar em um servidor até que expire. Ele não altera a máscara calculada. Um membro cujo communication_disabled_until está no futuro mantém todas as permissões que seus cargos concedem, e o Decoding Chat aplica a restrição como pré-condição separada em cada operação comunicante.

Enquanto o timeout está no futuro, estas operações falham com 403 COMMUNICATION_DISABLED:

• Enviar uma mensagem
• Editar a própria mensagem do chamador
• Adicionar uma reação
• Solicitar upload de anexo
• Iniciar indicador de digitação
• Alterar o próprio apelido do chamador

Um timeout não tem efeito em canal privado.

A ordem da pré-condição de timeout e da verificação de permissão varia por operação, portanto um chamador que está tanto em timeout quanto sem a permissão pode receber COMMUNICATION_DISABLED ou MISSING_PERMISSIONS.

Um cliente que controla sua interface pela máscara calculada TAMBÉM DEVE comparar communication_disabled_until com o tempo atual, pois a máscara ainda reporta SEND_MESSAGES para um membro em timeout.

Hierarquia de cargos

Os cargos são classificados por position, e a posição mais alta é a mais importante. Dois cargos com a mesma posição são classificados pelo snowflake, e o snowflake menor tem prioridade. A classificação de um membro é a classificação do cargo mais alto atribuído a ele, e um membro sem cargo atribuído fica abaixo de todos os cargos.

Um chamador gerencia um cargo quando sua classificação está estritamente acima da classificação do cargo. O dono do servidor gerencia todos os cargos. O cargo everyone fica na posição 0, portanto qualquer chamador com cargo acima dele o supera em classificação e pode modificá-lo. Ele nunca é alvo válido para uma mutação de posição ou posição de exibição destacada.

O Decoding Chat aplica a hierarquia independentemente de MANAGE_ROLES. Um chamador que possui a permissão sem superar o cargo alvo recebe 403 MISSING_PERMISSIONS. Um chamador cujo único MANAGE_ROLES vem do cargo everyone não tem cargo atribuído, portanto não pode gerenciar nenhum cargo.

Um não-proprietário não pode conceder uma permissão que não possui

Um bit solicitado fora das próprias permissões efetivas do servidor do chamador falha toda a requisição com MISSING_PERMISSIONS. O Decoding Chat executa essa verificação depois de descartar bits não atribuídos e lidar com bits controlados por feature como descreve Bits de permissão controlados por feature.

Objeto de cargo do servidor

Cargos são máscaras de permissão nomeadas que um servidor atribui a qualquer número de seus membros.

Estrutura

Campo	Tipo	Descrição
id	snowflake	O ID do cargo
name	string	O nome do cargo (1-100 caracteres)
color	integer	A cor do cargo como inteiro RGB, que toda operação neste recurso escreve no intervalo 0 a 16777215
position1	integer	A classificação do cargo na hierarquia de permissões, onde um valor maior é melhor classificado
hoist_position2	?integer	A classificação do cargo entre os grupos de lista de membros exibidos separadamente
permissions	decimal string	O bitfield de permissão que o cargo concede
hoist	boolean	Se os membros com o cargo são exibidos como seu próprio grupo na lista de membros
mentionable	boolean	Se um membro sem MENTION_EVERYONE pode mencionar o cargo
unicode_emoji?3	?string	O emoji Unicode exibido ao lado do nome do cargo

¹ O cargo everyone está sempre na posição 0, e todo outro cargo tem uma posição densa de 1 até o número de cargos restantes após qualquer mutação de hierarquia

² Um valor null significa que o cargo não tem posição explícita na lista de membros, e o cargo é então ordenado pela sua position de hierarquia

³ O campo está ausente de todo cargo que estas operações retornam e de todo cargo em um Gateway Dispatch de cargo

O cargo everyone tem o mesmo snowflake que seu servidor e é nomeado @everyone. Ele define o conjunto base de permissões para cada membro e não pode ser excluído, reordenado ou receber posição de exibição destacada. Sua cor e suas permissões permanecem mutáveis.

Exemplo

{
  "id": "1489002177550843904",
  "name": "Moderator",
  "color": 3447003,
  "position": 4,
  "hoist_position": 1,
  "permissions": "1099511637006",
  "hoist": true,
  "mentionable": false
}

Objeto de posição de cargo

Cada entrada nomeia um cargo e a classificação que o chamador solicita para ele.

Estrutura

Campo	Tipo	Descrição
id	snowflake	O ID do cargo
position?1	integer	A classificação que o chamador solicita para o cargo, onde um valor maior é melhor classificado

¹ O Decoding Chat ordena um cargo cuja entrada omite o campo pelo seu position armazenado, na mesma ordenação que as outras entradas. Um cargo cuja entrada solicita posição maior que o valor armazenado é colocado acima dele

Exemplo

[
  {"id": "1489002177550843904", "position": 3},
  {"id": "1489002177550843905", "position": 2}
]

Objeto de posição de exibição destacada de cargo

Cada entrada nomeia um cargo e a posição na lista de membros que ele recebe.

Estrutura

Campo	Tipo	Descrição
id	snowflake	O ID do cargo
hoist_position	integer	A posição na lista de membros a dar ao cargo

Exemplo

[
  {"id": "1489002177550843904", "hoist_position": 1}
]

Listar cargos do servidor

GET/v1/guilds/{guild_id}/rolesBotguilds

Retorna todo objeto de cargo do servidor no servidor, em ordem descendente de position, com empate resolvido por ID de cargo ascendente.

Limitações

• O chamador deve ser membro do servidor, e nenhuma permissão é requerida.
• Uma credencial bearer requer o escopo OAuth2 guilds.

Parâmetros de caminho

Campo	Tipo	Descrição
guild_id	snowflake	O ID do servidor

Resposta

Status	Corpo	Condição
200	array[cargo do servidor object]	Os cargos foram retornados
403	resposta de erro	Credencial bearer sem escopo guilds retorna MISSING_OAUTH_SCOPE, servidor indisponível retorna MISSING_ACCESS, ou chamador não é membro e retorna MISSING_PERMISSIONS
404	resposta de erro	O servidor não existe e retorna UNKNOWN_GUILD

Rate limit

60 requisições por 10 segundos para cada identidade autenticada e ID de servidor, no bucket guild:role:list::guild_id.

Criar cargo no servidor

POST/v1/guilds/{guild_id}/rolesBotAudit reason

Cria um cargo e retorna seu objeto de cargo do servidor. Requer MANAGE_ROLES, que é uma permissão elevada. Emite o evento Gateway Guild Role Create.

Limitações

• Um chamador que não é dono do servidor não pode conceder uma permissão ausente de suas próprias permissões efetivas no servidor.

A hierarquia de cargos não é avaliada. O novo cargo recebe a posição de hierarquia 1 e fica abaixo de todo cargo existente nessa posição. Nenhum outro cargo é renumerado. O cargo é criado sem posição de exibição destacada ou emoji Unicode e com hoist e mentionable definidos como false.

Parâmetros de caminho

Campo	Tipo	Descrição
guild_id	snowflake	O ID do servidor

Cabeçalhos da requisição

Campo	Tipo	Descrição
X-Fluxer-Features?	string	Uma declaração de feature separada por vírgulas

Corpo JSON

Campo	Tipo	Descrição
name	string	O nome do cargo (1-100 caracteres)
color?	integer	A cor do cargo como inteiro RGB de 24 bits (0-16777215, padrão 0)
permissions?1	decimal string | integer	O bitfield de permissão que o cargo concede

¹ Um campo omitido copia as permissões atuais do cargo everyone inalteradas. Um valor fornecido é interseccionado com o conjunto de bits definidos; o Decoding Chat limpa VIEW_CHANNEL_MEMBERS a menos que a declaração de feature do chamador inclua view_channel_members_permission, e então verifica o valor contra as próprias permissões do chamador

Resposta

Status	Corpo	Condição
200	objeto de cargo do servidor	O cargo foi criado
400	resposta de erro	O chamador não pode usar MANAGE_ROLES por causa do nível de MFA do servidor e a requisição retorna TWO_FACTOR_REQUIRED, ou o limite de cargos do servidor foi atingido e a requisição retorna MAX_GUILD_ROLES
403	resposta de erro	Credencial bearer é usada e retorna ACCESS_DENIED, servidor indisponível retorna MISSING_ACCESS, ou chamador não é membro, não tem MANAGE_ROLES, ou solicitou permissão que não possui, cada um retornando MISSING_PERMISSIONS
404	resposta de erro	O servidor não existe e retorna UNKNOWN_GUILD

Efeitos colaterais

A operação consome uma vaga de cargo do servidor e cria uma entrada ROLE_CREATE no log de auditoria do servidor com o motivo fornecido. Ela emite Guild Role Create para cada sessão que pode ver o servidor, incluindo a sessão atuante. Uma requisição que atinge o limite de cargos configurado falha com MAX_GUILD_ROLES e não consome vaga. O corpo da resposta tem o limite em um membro de nível superior max_guild_roles. O limite padrão é 250 cargos por servidor e conta o cargo everyone.

Rate limit

10 requisições por minuto para cada identidade autenticada e ID de servidor, no bucket guild:role:create::guild_id.

Modificar cargo do servidor

PATCH/v1/guilds/{guild_id}/roles/{role_id}BotAudit reason

Modifica um cargo e retorna seu objeto de cargo do servidor. Requer MANAGE_ROLES, que é uma permissão elevada. Emite o evento Gateway Guild Role Update.

Limitações

• Um chamador que não é dono do servidor também requer autoridade de hierarquia sobre o cargo alvo e não pode conceder uma permissão ausente de suas próprias permissões efetivas no servidor.

O cargo everyone é um alvo válido.

Parâmetros de caminho

Campo	Tipo	Descrição
guild_id	snowflake	O ID do servidor
role_id	snowflake	O ID do cargo

Cabeçalhos da requisição

Campo	Tipo	Descrição
X-Fluxer-Features?	string	Uma declaração de feature separada por vírgulas

Corpo JSON

Cada campo é opcional, e um campo omitido deixa o valor armazenado inalterado. position não é aceito aqui, pois apenas Modificar posições de cargos do servidor escreve a hierarquia.

Campo	Tipo	Descrição
name?1	string	O nome do cargo (1-100 caracteres)
color?	integer	A cor do cargo como inteiro RGB de 24 bits (0-16777215)
permissions?2	decimal string | integer	O bitfield de permissão substituto completo
hoist?1	boolean	Se os membros com o cargo são exibidos como seu próprio grupo na lista de membros
hoist_position?1	?integer	A posição na lista de membros a dar ao cargo, ou null para limpá-la
mentionable?1	boolean	Se um membro sem MENTION_EVERYONE pode mencionar o cargo

¹ O campo é aceito e ignorado quando o alvo é o cargo everyone, que não pode ser renomeado, exibido com destaque, receber posição na lista de membros ou ser mencionável

² O valor fornecido torna-se a máscara armazenada completa. Antes de verificar a autoridade do chamador, o Decoding Chat a intersecciona com o conjunto de bits definidos e mantém cada bit controlado por feature em seu valor armazenado a menos que a declaração de feature do chamador nomeie a feature para aquele bit

Resposta

Status	Corpo	Condição
200	objeto de cargo do servidor	O cargo foi modificado, ou cada valor fornecido já correspondia ao valor armazenado
400	resposta de erro	O chamador não pode usar MANAGE_ROLES por causa do nível de MFA do servidor e a requisição retorna TWO_FACTOR_REQUIRED
403	resposta de erro	Credencial bearer é usada e retorna ACCESS_DENIED, servidor indisponível retorna MISSING_ACCESS, ou chamador não é membro, não tem MANAGE_ROLES, não supera o cargo alvo em hierarquia, ou solicitou permissão que não possui, cada um retornando MISSING_PERMISSIONS
404	resposta de erro	O servidor não existe e retorna UNKNOWN_GUILD, ou o cargo não existe e retorna UNKNOWN_ROLE

Efeitos colaterais

A operação cria uma entrada ROLE_UPDATE no log de auditoria do servidor com o motivo fornecido e emite Guild Role Update para cada sessão que pode ver o servidor. Uma mudança de permissão adiciona uma entrada de mudança permissions_diff registrando os nomes de permissão exatos adicionados e removidos. Uma requisição cujos valores todos correspondem ao cargo atual ainda emite o Dispatch e não registra nenhuma entrada.

Rate limit

20 requisições por 10 segundos para cada identidade autenticada e ID de servidor, no bucket guild:role:update::guild_id.

Modificar posições de cargos do servidor

PATCH/v1/guilds/{guild_id}/rolesBotAudit reason

Reordena a hierarquia de cargos e retorna 204 com corpo vazio. Requer MANAGE_ROLES, que é uma permissão elevada. Emite o evento Gateway Guild Role Update Bulk.

Limitações

• O chamador precisa de autoridade de hierarquia sobre cada cargo cuja entrada fornece posição diferente do position armazenado do cargo.
• Uma entrada que omite o campo ou repete o valor armazenado é aceita sem essa verificação.

Uma mudança de posição de cargo concorrente no mesmo servidor pode retornar 423 GENERAL_ERROR.

Todo cargo que o chamador pode gerenciar é ordenado por sua posição solicitada em ordem descendente. Um cargo que não forneceu posição mantém sua posição armazenada como chave de ordenação, e qualquer empate restante é resolvido pela ordem atual. O Decoding Chat então coloca esses cargos de volta no mesmo conjunto de posições que ocupavam antes, portanto um cargo que o chamador não pode gerenciar nunca se move. Todo cargo exceto o everyone é então renumerado para uma posição densa. O cargo de maior classificação recebe o número de cargos exceto o everyone, o de menor classificação recebe 1, e o everyone permanece em 0.

Uma posição solicitada é uma chave de ordenação

A renumeração densa após a ordenação decide o valor armazenado, portanto ele pode diferir do solicitado. Um cliente lê o position resultante do payload Guild Role Update Bulk.

Parâmetros de caminho

Campo	Tipo	Descrição
guild_id	snowflake	O ID do servidor

Corpo JSON

O corpo de nível superior é um array de objetos de posição de cargo. Uma entrada que nomeia o cargo everyone é rejeitada com o código de validação CANNOT_REORDER_EVERYONE_ROLE, e um cargo que não existe no servidor é rejeitado com INVALID_ROLE_ID. Ambas as verificações ocorrem sobre o array inteiro antes da verificação de hierarquia e antes de qualquer escrita.

Resposta

Status	Corpo	Condição
204	vazio	As posições foram aplicadas
400	resposta de erro	Uma entrada nomeia o cargo everyone ou um cargo inexistente, ou o chamador não pode usar MANAGE_ROLES por causa do nível de MFA do servidor
403	resposta de erro	Credencial bearer é usada e retorna ACCESS_DENIED, servidor indisponível retorna MISSING_ACCESS, ou chamador não é membro, não tem MANAGE_ROLES, ou forneceu posição diferente do position armazenado de um cargo que não supera, cada um retornando MISSING_PERMISSIONS
404	resposta de erro	O servidor não existe e retorna UNKNOWN_GUILD
423	resposta de erro	Outra escrita de posição de cargo detém o bloqueio do servidor, retornando GENERAL_ERROR com Retry-After: 2

Efeitos colaterais

A operação cria uma entrada ROLE_UPDATE no log de auditoria do servidor para cada cargo que se moveu, conforme a regra de ordenação que o log de auditoria define. Emite um Guild Role Update Bulk com cada cargo cuja posição armazenada mudou para cada sessão que pode ver o servidor. Uma requisição que não produz mudança de posição não cria entrada de auditoria e não emite Dispatch. A renumeração densa pode alterar o position numérico de um cargo não nomeado sem alterar sua classificação, e tal cargo está incluído no Dispatch e não registra entrada de auditoria.

Rate limit

20 requisições por 10 segundos para cada identidade autenticada e ID de servidor, no bucket guild:role:positions::guild_id.

Modificar posições de exibição destacada de cargos

PATCH/v1/guilds/{guild_id}/roles/hoist-positionsBotAudit reason

Define a posição na lista de membros de um ou mais cargos e retorna 204 com corpo vazio. Requer MANAGE_ROLES, que é uma permissão elevada. Emite o evento Gateway Guild Role Update Bulk.

Limitações

• O chamador precisa de autoridade de hierarquia sobre cada cargo nomeado.
• O cargo everyone não pode receber posição de exibição destacada.

Uma posição de exibição destacada ordena os grupos da lista de membros exibidos separadamente, independentemente da hierarquia de permissões. Uma mudança de posição de exibição destacada concorrente no mesmo servidor pode retornar 423 GENERAL_ERROR.

Parâmetros de caminho

Campo	Tipo	Descrição
guild_id	snowflake	O ID do servidor

Corpo JSON

O corpo de nível superior é um array de objetos de posição de exibição destacada de cargo. Cada entrada fornece uma posição de exibição destacada, pois esta operação não pode limpá-la. O cargo everyone não pode aparecer no array e é rejeitado com o código de validação CANNOT_SET_HOIST_FOR_EVERYONE_ROLE, e um cargo que não existe no servidor é rejeitado com INVALID_ROLE_ID. Cada verificação ocorre sobre o array inteiro antes de qualquer escrita.

Resposta

Status	Corpo	Condição
204	vazio	As posições de exibição destacada foram aplicadas
400	resposta de erro	Uma entrada nomeia o cargo everyone ou um cargo inexistente, ou o chamador não pode usar MANAGE_ROLES por causa do nível de MFA do servidor
403	resposta de erro	Credencial bearer é usada e retorna ACCESS_DENIED, servidor indisponível retorna MISSING_ACCESS, ou chamador não é membro, não tem MANAGE_ROLES, ou não supera um cargo nomeado, cada um retornando MISSING_PERMISSIONS
404	resposta de erro	O servidor não existe e retorna UNKNOWN_GUILD
423	resposta de erro	Outra escrita de posição de exibição destacada detém o bloqueio do servidor, retornando GENERAL_ERROR com Retry-After: 2

Efeitos colaterais

A operação cria uma entrada ROLE_UPDATE no log de auditoria do servidor para cada cargo nomeado que se moveu na ordem da lista de membros, conforme a regra de ordenação que o log de auditoria define, e para cada cargo alterado que não está com exibição destacada. Emite um Guild Role Update Bulk com cada cargo cuja posição de exibição destacada mudou para cada sessão que pode ver o servidor. Definir as posições atuais novamente não muda nada, não cria entrada de auditoria e não emite Dispatch.

Rate limit

20 requisições por 10 segundos para cada identidade autenticada e ID de servidor, no bucket guild:role:hoist_positions::guild_id.

Redefinir posições de exibição destacada de cargos

DELETE/v1/guilds/{guild_id}/roles/hoist-positionsBotAudit reason

Limpa a posição na lista de membros de cada cargo no servidor e retorna 204 com corpo vazio. Requer MANAGE_ROLES, que é uma permissão elevada. Emite o evento Gateway Guild Role Update Bulk.

Limitações

• A hierarquia de cargos não é avaliada. A permissão sozinha limpa a posição de exibição destacada de cada cargo no servidor, incluindo cargos que o chamador não supera em hierarquia.

Uma mudança de posição de exibição destacada concorrente no mesmo servidor pode retornar 423 GENERAL_ERROR.

Parâmetros de caminho

Campo	Tipo	Descrição
guild_id	snowflake	O ID do servidor

A requisição não tem corpo.

Resposta

Status	Corpo	Condição
204	vazio	As posições de exibição destacada foram limpas, ou nenhum cargo tinha uma
400	resposta de erro	O chamador não pode usar MANAGE_ROLES por causa do nível de MFA do servidor e a requisição retorna TWO_FACTOR_REQUIRED
403	resposta de erro	Credencial bearer é usada e retorna ACCESS_DENIED, servidor indisponível retorna MISSING_ACCESS, ou chamador não é membro ou não tem MANAGE_ROLES, cada um retornando MISSING_PERMISSIONS
404	resposta de erro	O servidor não existe e retorna UNKNOWN_GUILD
423	resposta de erro	Outra escrita de posição de exibição destacada detém o bloqueio do servidor, retornando GENERAL_ERROR com Retry-After: 2

Efeitos colaterais

A operação cria uma entrada ROLE_UPDATE no log de auditoria do servidor para cada cargo limpo que se moveu na ordem da lista de membros, conforme a regra de ordenação que o log de auditoria define, e para cada cargo limpo que não está com exibição destacada. Emite um Guild Role Update Bulk com cada cargo limpo para cada sessão que pode ver o servidor. Quando nenhum cargo tinha posição de exibição destacada, nenhuma entrada de auditoria é criada e nenhum Dispatch é emitido.

Rate limit

10 requisições por minuto para cada identidade autenticada e ID de servidor, no bucket guild:role:hoist_positions_reset::guild_id.

Excluir cargo do servidor

DELETE/v1/guilds/{guild_id}/roles/{role_id}BotAudit reason

Exclui um cargo e retorna 204 com corpo vazio. Requer MANAGE_ROLES, que é uma permissão elevada. Emite o evento Gateway Guild Role Delete.

Limitações

• Um chamador que não é dono do servidor também requer autoridade de hierarquia sobre o cargo alvo.
• O cargo everyone não pode ser excluído.

Parâmetros de caminho

Campo	Tipo	Descrição
guild_id	snowflake	O ID do servidor
role_id	snowflake	O ID do cargo

A requisição não tem corpo.

Resposta

Status	Corpo	Condição
204	vazio	O cargo foi excluído
400	resposta de erro	O chamador não pode usar MANAGE_ROLES por causa do nível de MFA do servidor e a requisição retorna TWO_FACTOR_REQUIRED
403	resposta de erro	Credencial bearer é usada e retorna ACCESS_DENIED, servidor indisponível retorna MISSING_ACCESS, ou chamador não é membro, não tem MANAGE_ROLES, ou não supera o cargo alvo, cada um retornando MISSING_PERMISSIONS
404	resposta de erro	O servidor não existe e retorna UNKNOWN_GUILD, ou o cargo não existe ou é o cargo everyone, cada um retornando UNKNOWN_ROLE

A exclusão é irreversível e reescreve cada membro afetado

Um cargo excluído não pode ser restaurado, e suas permissões, cor e estado de exibição destacada vão com ele. Uma substituição que o nomeia não afeta mais nenhuma máscara calculada. Cada membro que possuía o cargo o perde na mesma operação, portanto qualquer um que dependia dele para acesso ao canal perde esse acesso imediatamente.

Efeitos colaterais

A operação remove o cargo de cada membro que o possuía, remove o registro do cargo e libera a vaga de cargo do servidor que ele ocupava. Ela cria uma entrada ROLE_DELETE no log de auditoria do servidor com o motivo de auditoria fornecido e emite Guild Role Delete para cada sessão que pode ver o servidor. O cargo excluído não aparece mais em roles em uma leitura posterior de membro ou no payload Guild Member Update.

Rate limit

10 requisições por minuto para cada identidade autenticada e ID de servidor, no bucket guild:role:delete::guild_id.