Servidores (Guilds)

Um canal de servidor é uma das salas nas quais um servidor é dividido, incluindo as categorias que os agrupam. As operações aqui listam, criam e reordenam os canais de um servidor, e o Recurso de canais define o objeto de canal e todas as operações por canal.

Regras de acesso

Toda operação aqui retorna 404 UNKNOWN_GUILD para um servidor que não existe. Um chamador que não é membro de um servidor existente recebe 403 MISSING_PERMISSIONS.

Uma solicitação cujo caminho nomeia um servidor que possui UNAVAILABLE_FOR_EVERYONE é recusada com 403 MISSING_ACCESS antes que a operação seja executada.

Tipos de canais de servidor

Estes são os tipos de canais que podem existir dentro de um servidor, e exatamente os valores que Criar canal de servidor aceita em type.

Valor	Nome	Descrição
0	GUILD_TEXT	Canal de texto que possui mensagens e modo lento (slowmode)
2	GUILD_VOICE	Canal de voz que possui mensagens, sessões de voz e transmissões ao vivo (Go Live)
4	GUILD_CATEGORY	Categoria que agrupa outros canais do servidor e fornece substituições de permissão herdadas
998	GUILD_LINK	Canal cujo único conteúdo é uma URL de destino externa

Objeto de criação de substituição de permissão

A coleção inicial de substituições fornecida quando um canal é criado. A forma armazenada retornada posteriormente é o objeto de substituição de permissão.

Estrutura

Campo	Tipo	Descrição
id	snowflake	O ID do cargo ou membro que a substituição afeta
type¹	integer	Tipo de substituição de permissão
allow?²	decimal string	Os bits de permissão que a substituição concede (padrão 0)
deny?²	decimal string	Os bits de permissão que a substituição remove (padrão 0)

¹ Obrigatório. 0 nomeia um cargo e 1 nomeia um membro, e nenhum outro valor é aceito

² Uma string decimal de no máximo 9223372036854775807, ou um inteiro JSON de no máximo 9007199254740991. Nulo é rejeitado

Uma string decimal maior retorna 400 INVALID_FORM_BODY com o código INTEGER_OUT_OF_INT64_RANGE. Um número JSON fora do intervalo seguro de inteiros retorna INVALID_INTEGER_FORMAT, assim como uma string que não é composta apenas por dígitos.

Um bit que não nomeia nenhuma permissão definida nunca falha na comparação de autoridade descrita por Criar canal de servidor. Ele é armazenado conforme fornecido e retornado por todas as leituras posteriores do canal.

Um bit definido em ambas as máscaras é resolvido como uma permissão concedida durante a computação de permissão.

Exemplo

{
  "id": "1501314428688998182",
  "type": 0,
  "allow": "1024",
  "deny": "2048"
}

Objeto de posição de canal

Uma entrada da atualização em massa da hierarquia. As entradas são aplicadas na ordem do array, cada uma contra o resultado da anterior.

Estrutura

Campo	Tipo	Descrição
id	snowflake	O ID do canal a ser movido
position?¹	integer	Índice entre os irmãos de destino (mínimo 0)
parent_id?²	?snowflake	Nova categoria pai, ou nulo para mover o canal para a raiz do servidor
preceding_sibling_id?³	?snowflake	Irmão que fica diretamente antes deste canal, ou nulo para colocá-lo em primeiro lugar
lock_permissions?⁴	boolean	Se as substituições da categoria de destino devem ser copiadas para o canal movido (padrão false)

¹ Lido apenas quando preceding_sibling_id é omitido. Quando preceding_sibling_id é enviado, inclusive como nulo, o Decoding Chat ignora position

² Um campo omitido mantém o pai atual do canal. Uma categoria associada a qualquer pai é recusada com CATEGORIES_CANNOT_HAVE_PARENTS

³ Um irmão precedente deve compartilhar o pai de destino, portanto, uma categoria só é válida aqui quando o destino do canal movido é a raiz do servidor

⁴ A cópia é executada apenas quando a mesma entrada também move o canal para uma categoria, e ela substitui as substituições do canal movido

Um position além do último irmão de destino coloca o canal em último lugar. Omitir tanto position quanto preceding_sibling_id coloca um canal de voz por último e qualquer outro canal diretamente antes do primeiro irmão de voz.

Nomear uma categoria como irmão precedente coloca o canal movido após essa categoria e após todos os canais já contidos nela.

Exemplo

{
  "id": "1501314428688998182",
  "parent_id": "1501314428688998100",
  "preceding_sibling_id": null,
  "lock_permissions": true
}

Listar canais do servidor

GET/v1/guilds/{guild_id}/channels

Bot

Retorna todos os objetos de canal no servidor que o membro autenticado pode ver. A participação no servidor é o único requisito.

O Decoding Chat avalia a visibilidade do canal por canal. Um canal é incluído quando o membro possui VIEW_CHANNEL nele, ou quando o membro possui acesso temporário a ele através de uma transição de voz. Uma categoria é incluída quando pelo menos um filho concede ao membro VIEW_CHANNEL. Um membro sem canais visíveis recebe um array vazio.

Um servidor contém no máximo o limite configurado na instância max_guild_channels, cujo padrão é 500.

Parâmetros de caminho

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

Resposta

Status	Corpo	Condição
200	array[objeto de canal]	Canais visíveis foram retornados
403	resposta de erro	O chamador não é membro do servidor, retornando `MISSING_PERMISSIONS`
404	resposta de erro	O servidor não existe, retornando `UNKNOWN_GUILD`

Limite de taxa

60 solicitações por 10 segundos para cada usuário autenticado e ID de servidor, no bucket guild:channels:list::guild_id.

Criar canal de servidor

POST/v1/guilds/{guild_id}/channels

Bot Audit reason MFA

Cria um canal de servidor e retorna seu objeto de canal com status 200. Requer MANAGE_CHANNELS no nível do servidor. Emite um evento de Gateway Channel Create.

Limitações

Fornecer permission_overwrites também requer MANAGE_ROLES no nível do servidor.

MANAGE_CHANNELS é uma permissão elevada, portanto, também requer um autenticador multifator registrado quando o nível de MFA do servidor for elevado e o chamador não for o proprietário do servidor.

Parâmetros de caminho

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

Corpo JSON

type é obrigatório e decide que tipo de canal é criado. Todo tipo aceita o mesmo conjunto de campos, então um campo que não tem significado para o tipo selecionado é aceito e depois ignorado.

Campo	Tipo	Descrição
type	integer	Tipo de canal do servidor
name¹²	string	Nome do canal (1-100 caracteres após a normalização)
topic?	?string	Tópico do canal (1-1024 caracteres)
url?³	?string	URL de destino para um canal de link
parent_id?⁴	?snowflake	Categoria pai
bitrate?⁵¹¹	?integer	Taxa de bits do canal de voz em bits por segundo (8000-384000, padrão 64000)
user_limit?⁵⁶	?integer	Limite de ocupação do canal de voz (0-99, padrão 0)
voice_connection_limit?⁵	?integer	Conexões de voz simultâneas permitidas para um usuário em um canal de voz (1-100, padrão 5)
rate_limit_per_user?	?integer	Intervalo de modo lento (slowmode) em segundos (0-21600, padrão 0)
permission_overwrites?⁷	array[objeto de criação de substituição de permissão]	Coleção completa de substituições iniciais
nsfw?⁸	boolean	Restrição de idade legada para este canal (padrão false)
nsfw_override?⁸	?boolean	Restrição de idade explícita, ou nulo para herdar da categoria pai e então do servidor
content_warning_level?⁹	integer	Nível de aviso de conteúdo (padrão 0)
content_warning_text?¹⁰	?string	Texto de aviso de conteúdo (máx. 200 caracteres), ou nulo para herdar

¹ A normalização remove pontos de controle, junção, bidirecionais e de tag, colapsa execuções de espaço em branco para um espaço e apara (trim). Um resultado vazio é rejeitado com NAME_EMPTY_AFTER_NORMALIZATION

² O nome de um canal de texto também é convertido para letras minúsculas, seus espaços em branco são substituídos por hífens e a pontuação ASCII, exceto -, ., e _, é removida, a menos que o servidor tenha TEXT_CHANNEL_FLEXIBLE_NAMES. Essa passagem reescreve o nome armazenado e nunca falha a solicitação

³ Uma URL http ou https de no máximo 2048 caracteres com um host e sem credenciais incorporadas. É armazenado para todos os tipos de canal

⁴ Nomeia uma categoria no mesmo servidor. Uma categoria não pode ter um pai

⁵ Armazenado apenas para a variante de voz, onde o padrão declarado se aplica quando o campo é omitido ou nulo, e descartado para todos os outros tipos

⁶ O valor 0 significa nenhum limite de ocupação

⁷ Quando omitido, um novo canal com uma categoria pai copia as substituições atuais dessa categoria. Um campo presente substitui completamente essa herança, inclusive com um array vazio. Nulo é rejeitado

⁸ nsfw_override tem precedência, e nsfw fornece o valor apenas quando nsfw_override está ausente. Omitir ambos armazena um explícito false, e apenas um nsfw_override nulo é herdado

⁹ O valor 1 ativa o aviso neste canal. Todo outro valor aceito armazena 0 e herda da categoria pai e então do servidor

¹⁰ O valor é aparado (trim), e um resultado vazio é armazenado como nulo

¹¹ O valor armazenado é limitado a 96000 a menos que o servidor possua um recurso de taxa de bits de áudio. Um valor superior é armazenado no limite em vez de ser rejeitado

Um valor maior que 10000 caracteres é rejeitado com STRING_LENGTH_INVALID antes que a normalização seja executada. Um pai que não existe neste servidor retorna INVALID_PARENT_CHANNEL, e um que não é uma categoria retorna PARENT_MUST_BE_CATEGORY.

O servidor contém no máximo o limite configurado na instância max_guild_channels, cujo padrão é 500, e uma categoria pai contém no máximo max_channels_per_category, cujo padrão é 50. Alcançar o limite do servidor retorna 400 MAX_GUILD_CHANNELS e alcançar o limite da categoria retorna 400 MAX_CATEGORY_CHANNELS. Cada mensagem de erro indica o limite resolvido. O novo canal é criado sem região RTC.

O novo canal ocupa uma posição derivada de seus irmãos. Uma categoria, e um canal criado sem pai, é colocado após a posição mais alta no servidor. Um canal de voz criado dentro de uma categoria é colocado após o último irmão de voz, ou após o último texto ou canal de link irmão quando a categoria não possui canal de voz. Um canal de texto ou link é colocado após o último irmão de texto ou link, e um canal sem tal irmão é colocado diretamente após a própria categoria. O resto do servidor não é renumerado, portanto, dois canais podem manter a mesma posição armazenada até a próxima atualização de hierarquia reenumerá-los.

Apenas a máscara permitida é comparada, de modo que um deny (negação) fornecido é armazenado sem qualquer verificação de autoridade. Um chamador com ADMINISTRATOR nesse contexto possui todos os bits, e cada bit solicitado passa.

Resposta

Status	Corpo	Condição
200	objeto de canal	O canal foi criado
400¹²	resposta de erro	O corpo, tipo, nome, pai, URL, configuração de voz ou texto de aviso de conteúdo é inválido, um limite de canais foi alcançado ou o chamador não possui autenticador registrado em um servidor com MFA elevado
403	resposta de erro	O chamador não possui `MANAGE_CHANNELS`, não é membro do servidor, forneceu substituições sem `MANAGE_ROLES`, ou permitiu uma permissão que não possui no contexto pai, cada um retornando `MISSING_PERMISSIONS`
404	resposta de erro	O servidor não existe, retornando `UNKNOWN_GUILD`

¹ Uma falha no esquema ou pai retorna INVALID_FORM_BODY e nomeia o campo com CATEGORIES_CANNOT_HAVE_PARENTS, INVALID_PARENT_CHANNEL, ou PARENT_MUST_BE_CATEGORY. Uma falha de capacidade retorna o limite superior MAX_GUILD_CHANNELS ou MAX_CATEGORY_CHANNELS

² O código de autenticador ausente é TWO_FACTOR_REQUIRED, retornado apenas após MANAGE_CHANNELS ser confirmado, de modo que um chamador sem a permissão recebe 403 em seu lugar

Efeitos colaterais

A operação consome um slot de canal do servidor e, quando um pai é fornecido, um slot nessa categoria. Ela cria uma entrada no log de auditoria do servidor CHANNEL_CREATE com o motivo fornecido, mais uma entrada CHANNEL_OVERWRITE_CREATE para cada substituição armazenada, independentemente de a substituição ter sido fornecida ou herdada. Alcançar qualquer limite de canal falha a solicitação sem consumir um slot.

Ela emite Channel Create com o objeto de canal completo apenas para as sessões que podem visualizar o novo canal.

Limite de taxa

10 solicitações por minuto para cada usuário autenticado e ID de servidor, no bucket guild:channel:create::guild_id.

Modificar posições dos canais do servidor

PATCH/v1/guilds/{guild_id}/channels

Bot MFA

Aplica uma atualização de hierarquia de canais do servidor e retorna 204 com um corpo vazio. Requer MANAGE_CHANNELS no nível do servidor. Emite um evento Gateway Channel Update Bulk para cada entrada que altera a ordem.

Limitações

Definir lock_permissions em uma entrada que altera o pai também requer MANAGE_ROLES no canal movido.
A operação não registra entrada no log de auditoria do servidor, portanto um cabeçalho X-Audit-Log-Reason não tem efeito.

Atualizações simultâneas de hierarquia para o mesmo servidor podem retornar 423 GENERAL_ERROR com um cabeçalho Retry-After de dois segundos.

Um canal, pai ou irmão desconhecido rejeita a solicitação inteira. O Decoding Chat aplica as entradas uma a uma. Quando uma entrada posterior falha em uma verificação após essa verificação de existência, incluindo a verificação de autoridade lock_permissions, toda entrada anterior permanece aplicada. Mover uma categoria move seus filhos com ela, e nem a categoria nem seus filhos contam como irmãos de destino.

Após uma movimentação, as posições seguem consecutivamente a partir de 1 em todo o servidor. Cada categoria é seguida por seus filhos, com os canais de texto e link antes dos canais de voz.

Parâmetros de caminho

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

Corpo JSON

O corpo principal é um array de objetos de posição de canal de qualquer tamanho, incluindo zero. Cada canal, pai e irmão que uma entrada nomeia deve existir neste servidor. Uma categoria não pode receber um pai, e um pai que não seja uma categoria é recusado. Um canal não pode ser posicionado em relação a si mesmo ou a um de seus próprios filhos. Mover um canal para uma categoria cheia é recusado com 400 MAX_CATEGORY_CHANNELS.

Canais na raiz do servidor estão isentos dessa restrição.

Resposta

Status	Corpo	Condição
204	vazio	A hierarquia de canais foi aplicada
400¹²	resposta de erro	Uma entrada é estruturalmente inválida, a categoria de destino está cheia, ou o chamador não possui autenticador registrado em um servidor com MFA elevado
403	resposta de erro	O chamador não possui `MANAGE_CHANNELS`, não é membro do servidor, ou definiu `lock_permissions` sem autoridade suficiente no canal movido, cada um retornando `MISSING_PERMISSIONS`
404	resposta de erro	O servidor não existe, retornando `UNKNOWN_GUILD`
423	resposta de erro	Outra atualização de hierarquia para este servidor está em andamento, retornando `GENERAL_ERROR`

¹ Uma falha estrutural retorna INVALID_FORM_BODY e nomeia o campo com CHANNEL_NOT_FOUND, INVALID_CHANNEL_ID, INVALID_PARENT_CHANNEL, PARENT_MUST_BE_CATEGORY, CATEGORIES_CANNOT_HAVE_PARENTS, PRECEDING_CHANNEL_MUST_SHARE_PARENT, CANNOT_POSITION_CHANNEL_RELATIVE_TO_ITSELF, ou VOICE_CHANNELS_CANNOT_BE_ABOVE_TEXT_CHANNELS. Uma categoria de destino cheia retorna o erro de alto nível MAX_CATEGORY_CHANNELS

² O código de autenticador ausente é TWO_FACTOR_REQUIRED, retornado apenas após MANAGE_CHANNELS ser confirmado, de modo que um chamador sem a permissão recebe 403 em seu lugar

Efeitos colaterais

Cada entrada que altera a ordem emite Channel Update Bulk com a hierarquia resultante filtrada para os canais que cada destinatário pode ver.

Quando lock_permissions copia as substituições da categoria de destino, leia novamente o canal movido para obtê-las. A cópia não gera evento no Gateway ou entrada de auditoria.

A cópia requer MANAGE_ROLES no canal movido. O chamador também deve possuir todos os bits de permissão (allow) que a cópia adiciona e todos os bits de negação (deny) que a cópia remove. Autoridade insuficiente retorna 403 MISSING_PERMISSIONS, mas a movimentação do canal continua aplicada.

Limite de taxa

30 solicitações por 10 segundos para cada usuário autenticado e ID de servidor, no bucket guild:channel:positions::guild_id.