Canais

Um canal é onde ocorre uma conversa, por texto ou voz. Um servidor possui canais de texto, voz, categoria e link. Fora de um servidor, um canal é uma mensagem direta, uma mensagem direta em grupo ou o canal de notas pessoais.

Mensagens define conteúdo de mensagem, e Canais do servidor define listagem, criação e reordenação no escopo de servidor. Chamadas define chamadas, a região de uma chamada privada e encerramento de chamada. Transmissões define as chaves de transmissão e prévias de um compartilhamento de tela Go Live.

Objeto de canal

Um objeto de canal sempre possui sua identidade e tipo. Todos os outros campos estão presentes apenas para os tipos de canal que os possuem.

Estrutura

Campo	Tipo	Descrição
id	snowflake	O ID do canal
type	integer	O tipo do canal
guild_id?	snowflake	O ID do servidor, presente apenas para canal de texto, voz, categoria ou link de servidor
name?¹	string	O nome do canal, presente para canal de servidor e mensagem direta em grupo
topic?	?string	O tópico do canal, presente apenas para canal de texto ou voz de servidor
url?	?string	A URL de destino, presente apenas para canal de link de servidor
icon?	?string	O hash do ícone, presente apenas para mensagem direta em grupo
owner_id?	?snowflake	O ID do proprietário, presente apenas para mensagem direta em grupo
position?²	integer	A posição de ordenação, presente apenas para canal de servidor
parent_id?	?snowflake	O ID da categoria pai, null quando o canal fica no nível superior
bitrate?³	?integer	A taxa de bits de voz em bits por segundo, presente apenas para canal de voz de servidor
user_limit?⁴	?integer	O limite configurado de ocupação de membros, presente apenas para canal de voz de servidor
voice_connection_limit?⁵	?integer	O número de conexões de voz simultâneas que um usuário pode manter, presente apenas para canal de voz de servidor
rtc_region?⁶	?string	O ID da região RTC selecionada, presente apenas para canal de voz de servidor
last_message_id?	?snowflake	O ID da mensagem mais recente, null quando o canal não tem nenhuma
last_pin_timestamp?	?ISO8601 timestamp	O horário em que uma mensagem foi fixada mais recentemente, ou null quando nada foi fixado
permission_overwrites?⁷	array[substituição de permissão object]	As substituições aplicadas a este canal, presentes apenas para canal de servidor
recipients?⁸	array[usuário parcial object]	Os outros destinatários de uma mensagem direta ou mensagem direta em grupo (máx. 49)
nsfw?⁹	boolean	Se o canal tem sua própria restrição de idade, presente apenas para canal de servidor
nsfw_override?⁹	?boolean	Se este canal sobrepõe a restrição de idade herdada, ou null quando herda
content_warning_level?¹⁰	integer	O nível de aviso de conteúdo armazenado neste canal, presente apenas para canal de servidor
content_warning_text?¹⁰	?string	O texto de aviso de conteúdo armazenado neste canal, ou null quando o canal herda
rate_limit_per_user?¹¹	integer	O intervalo de modo lento em segundos, presente apenas para canal de texto ou voz de servidor
nicks?¹²	map[snowflake, string]	Os apelidos da mensagem direta em grupo com chave pelo ID decimal do usuário (cada 1-32 caracteres)

¹ Omitido quando uma mensagem direta em grupo não armazena nome, e nunca presente em mensagem direta ou no canal de notas pessoais

² Um canal que não armazena posição reporta 0

³ Um canal de voz de servidor que não armazena taxa de bits reporta 0

⁴ O valor 0 significa sem limite de ocupação

⁵ O padrão é 5 em um canal de voz de servidor que não armazena limite de conexões por usuário

⁶ Null seleciona roteamento automático. Listar regiões RTC retorna os identificadores disponíveis

⁷ Sempre presente para um canal de servidor, e vazio quando o canal não armazena substituição

⁸ Exclui o usuário autenticado, omitido totalmente quando nenhum outro destinatário permanece, e nunca presente no canal de notas pessoais

⁹ Um canal sem sobreposição explícita reporta nsfw false e nsfw_override null

¹⁰ Em um canal que herda, content_warning_level é 0 e content_warning_text é null

¹¹ O intervalo é 0 quando o canal não configura modo lento

¹² Omitido quando o grupo não armazena apelido. Limpar um apelido remove sua chave do mapa

Uma categoria não possui parent_id. Um cliente que lê a chave ausente como null vê um canal cujo pai foi limpo.

Uma restrição de idade e um aviso de conteúdo resolvem primeiro através deste canal, depois da categoria pai e finalmente do servidor. Uma categoria não possui categoria pai e resolve através de si mesma e depois do servidor.

Exemplo

{
  "id": "1501314428688998182",
  "type": 0,
  "guild_id": "1501314428688990000",
  "name": "geral",
  "topic": "Qualquer assunto",
  "position": 3,
  "parent_id": "1501314428688991111",
  "permission_overwrites": [],
  "nsfw": false,
  "nsfw_override": null,
  "content_warning_level": 0,
  "content_warning_text": null,
  "rate_limit_per_user": 0,
  "last_message_id": "1501320000000000000",
  "last_pin_timestamp": null
}

Tipos de canal

Valor	Nome	Descrição
0	GUILD_TEXT	Canal de texto de servidor
1	DM	Canal de mensagem direta entre exatamente duas contas
2	GUILD_VOICE	Canal de voz de servidor, que também possui mensagens, fixados e modo lento
3	GROUP_DM	Canal de mensagem direta em grupo
4	GUILD_CATEGORY	Categoria de servidor, que não possui pai nem mensagens
998	GUILD_LINK	Canal de link de servidor, que possui URL de destino e não possui mensagens
999	DM_PERSONAL_NOTES¹	Canal de notas pessoais

¹ Seu ID de canal é exatamente o ID do usuário proprietário, e não possui destinatário nem nome. O Decoding Chat o cria no primeiro acesso autenticado

Objeto de substituição de permissão

Uma substituição de permissão altera as permissões efetivas do servidor para um cargo ou um membro em um canal. allow e deny são strings decimais porque uma máscara de permissão excede o intervalo que um número JSON preserva. Permissões define os flags individuais.

Estrutura

Campo	Tipo	Descrição
id¹	snowflake	O ID do cargo ou membro
type	integer	O tipo de substituição de permissão do identificador em `id`
allow²	decimal string	O bitfield de permissões que esta substituição permite
deny²	decimal string	O bitfield de permissões que esta substituição nega

¹ Um identificador aborda uma substituição, portanto armazenar uma substituição para um identificador que já possui uma a substitui, mesmo quando ambos nomeiam tipos diferentes

² Todos os bits fora do conjunto de permissões definido são descartados na escrita, e ambos os campos são 0 quando a substituição não concede nem nega nada

Nenhuma rota limita o número de substituições que um canal armazena. Modificar canal e Criar canal no servidor aceitam um array permission_overwrites de qualquer tamanho, e nenhuma chave de limite o limita.

Exemplo

{
  "id": "1501314428688990000",
  "type": 0,
  "allow": "3072",
  "deny": "0"
}

Tipos de substituição de permissão

Valor	Nome	Descrição
0	ROLE	A substituição aplica-se a um cargo do servidor
1	MEMBER	A substituição aplica-se a um membro do servidor

Níveis de aviso de conteúdo

Valor	Nome	Descrição
0	INHERIT	Herdar o aviso de conteúdo da categoria pai e depois do servidor
1	CONTENT_WARNING	Aplicar o aviso de conteúdo armazenado neste canal

Objeto de estado do modo lento do canal

O estado do modo lento combina o intervalo configurado do canal com o próximo horário de envio permitido do usuário autenticado.

Estrutura

Campo	Tipo	Descrição
rate_limit_per_user	integer	O intervalo configurado do modo lento em segundos, ou `0` quando o modo lento está desabilitado
retry_after_ms¹	integer	O atraso restante em milissegundos antes que o usuário possa enviar
next_send_allowed_at¹	?ISO8601 timestamp	O próximo horário de envio permitido, ou null quando nenhum atraso se aplica
can_bypass²	boolean	Se o usuário ignora o modo lento através de BYPASS_SLOWMODE

¹ Ambos reportam nenhum atraso em canal privado, para intervalo de 0, para chamador bot e para chamador com BYPASS_SLOWMODE

² True apenas para chamador não-bot com BYPASS_SLOWMODE em um canal de servidor com intervalo diferente de zero, portanto um chamador bot e um canal privado reportam false embora nenhum dos dois seja atrasado

Exemplo

{
  "rate_limit_per_user": 10,
  "retry_after_ms": 4200,
  "next_send_allowed_at": "2026-08-31T09:14:02.000Z",
  "can_bypass": false
}

Objeto de região RTC

Uma região RTC nomeia um destino de roteamento de voz que a implantação opera. Seu identificador é o valor que um canal de voz de servidor armazena em rtc_region, e o nome e emoji existem apenas para exibição.

Estrutura

Campo	Tipo	Descrição
id	string	O ID da região RTC
name	string	O nome exibido para a região em um cliente
emoji	string	O emoji que o operador configurou para a região

Exemplo

{
  "id": "eu-central",
  "name": "Frankfurt",
  "emoji": "🇩🇪"
}

Obter canal

GET/v1/channels/{channel_id}

Bot

Retorna o objeto de canal visível para o usuário autenticado.

Limitações

Um canal de servidor requer VIEW_CHANNEL e verificação de idade satisfeita quando resolve para uma restrição de idade.
Um canal privado requer acesso de destinatário atual.
O canal de notas pessoais requer propriedade.

O Decoding Chat impõe verificação de idade apenas para canal de texto, voz ou link de servidor. O Decoding Chat nunca exige verificação de idade para uma categoria de servidor, mesmo quando a categoria tem a sobreposição que seus filhos herdam.

Parâmetros de caminho

Campo	Tipo	Descrição
channel_id	snowflake	O ID do canal a retornar

Resposta

Status	Corpo	Condição
200	canal object	O canal foi retornado
403	resposta de erro	O chamador não é membro do servidor ou não possui `VIEW_CHANNEL`, cada um retornando `MISSING_PERMISSIONS`
403	resposta de erro	O servidor existe, mas o estado de membro do chamador não pode ser resolvido e a requisição retorna `ACCESS_DENIED`
403	resposta de erro	A restrição de idade resolvida não foi satisfeita e a requisição retorna `NSFW_CONTENT_AGE_RESTRICTED`
404	resposta de erro	O canal não existe, ou o chamador não é destinatário do canal privado, cada um retornando `UNKNOWN_CHANNEL`, ou o servidor proprietário do canal não existe e a requisição retorna `UNKNOWN_GUILD`

Efeitos colaterais

Solicitar o canal de notas pessoais do usuário autenticado o cria quando ainda não existir, e o retorna sem Dispatch de Channel Create.

Rate limit

100 requisições por 10 segundos para cada usuário autenticado e ID de canal, no bucket channel:read::channel_id.

Obter estado do modo lento do canal

GET/v1/channels/{channel_id}/slowmode

Bot

Retorna o objeto de estado do modo lento do canal do usuário autenticado. O chamador precisa do mesmo acesso de Obter canal.

Parâmetros de caminho

Campo	Tipo	Descrição
channel_id	snowflake	O ID do canal cujo estado de modo lento é retornado

Resposta

Status	Corpo	Condição
200	estado do modo lento do canal object	O estado foi retornado
403	resposta de erro	O chamador não é membro do servidor ou não possui `VIEW_CHANNEL`, cada um retornando `MISSING_PERMISSIONS`
403	resposta de erro	O servidor existe, mas o estado de membro do chamador não pode ser resolvido e a requisição retorna `ACCESS_DENIED`
403	resposta de erro	A restrição de idade resolvida não foi satisfeita e a requisição retorna `NSFW_CONTENT_AGE_RESTRICTED`
404	resposta de erro	O canal não existe, ou o chamador não é destinatário do canal privado, cada um retornando `UNKNOWN_CHANNEL`, ou o servidor proprietário do canal não existe e a requisição retorna `UNKNOWN_GUILD`

Efeitos colaterais

A leitura não avança a contagem regressiva de modo lento do chamador. Solicitar o canal de notas pessoais do usuário autenticado o cria quando ainda não existir, sem Dispatch de Channel Create.

Rate limit

100 requisições por 10 segundos para cada usuário autenticado e ID de canal, no bucket channel:read::channel_id.

Listar regiões RTC

GET/v1/channels/{channel_id}/rtc-regions

Retorna os objetos de região RTC que o usuário autenticado pode selecionar para um canal de voz de servidor, em ordem ascendente de nome de exibição. Exclusivo para usuários.

Limitações

O chamador precisa do mesmo acesso de Obter canal.
O canal deve ser um canal de voz de servidor.

Apenas regiões disponíveis para o chamador são retornadas. O array pode estar vazio.

Parâmetros de caminho

Campo	Tipo	Descrição
channel_id	snowflake	O ID do canal de voz do servidor

Resposta

Status	Corpo	Condição
200	array[região RTC object]	Regiões disponíveis foram retornadas
400	resposta de erro	O canal não é um canal de voz de servidor e a requisição retorna `INVALID_CHANNEL_TYPE`
403	resposta de erro	O chamador é um bot ou usa credencial bearer OAuth2, ou o servidor existe mas o estado de membro do chamador não pode ser resolvido, cada um retornando `ACCESS_DENIED`
403	resposta de erro	O chamador não é membro do servidor ou não possui `VIEW_CHANNEL` e a requisição retorna `MISSING_PERMISSIONS`
403	resposta de erro	A restrição de idade resolvida não foi satisfeita e a requisição retorna `NSFW_CONTENT_AGE_RESTRICTED`
404	resposta de erro	O canal não existe e a requisição retorna `UNKNOWN_CHANNEL`, ou o servidor proprietário não existe e a requisição retorna `UNKNOWN_GUILD`

Rate limit

100 requisições por 10 segundos para cada usuário autenticado e ID de canal, no bucket channel:read::channel_id.

Modificar canal

PATCH/v1/channels/{channel_id}

Bot Audit reason

Modifica um canal de servidor ou mensagem direta em grupo e retorna o objeto de canal atualizado. Emite um evento de Gateway Channel Update.

Limitações

Um canal de servidor requer VIEW_CHANNEL e MANAGE_CHANNELS naquele canal.
Fornecer permission_overwrites também requer MANAGE_ROLES naquele canal.
Fornecer rtc_region em um canal de voz de servidor também requer UPDATE_RTC_REGION.
Um chamador que não seja o proprietário do servidor não pode permitir um bit de permissão fora de suas próprias permissões efetivas naquele canal, e nem remover um bit negado fora delas.
Uma mensagem direta em grupo requer que o chamador seja um destinatário atual.
A transferência de propriedade requer que o chamador seja o proprietário atual, assim como definir o apelido de outro destinatário ou limpar todos os apelidos.

MANAGE_CHANNELS e MANAGE_ROLES são permissões elevadas. Cada uma também requer um autenticador multifator registrado quando o nível MFA do servidor é elevado e o chamador não é o proprietário do servidor. Um chamador que possui a permissão sem esse autenticador recebe 400 TWO_FACTOR_REQUIRED.

Definir substituição de permissão no canal e Excluir substituição de permissão no canal alteram uma única substituição por vez e mantêm as demais intocadas.

Parâmetros de caminho

Campo	Tipo	Descrição
channel_id	snowflake	O ID do canal a modificar

Cabeçalhos da requisição

Campo	Tipo	Descrição
X-Fluxer-Features?¹	string	Uma declaração de recurso separada por vírgula

¹ Lido apenas quando permission_overwrites é fornecido. Um bit restrito por recurso que a declaração não nomeia é copiado da substituição armazenada

Corpo JSON

O tipo de canal armazenado seleciona a variante do corpo, e um campo type na requisição é ignorado. Uma mensagem direta e o canal de notas pessoais não correspondem a nenhuma variante, e o Decoding Chat rejeita ambos com 400 INVALID_FORM_BODY.

Corpo para canal de servidor

Todos os campos são opcionais, e um campo omitido preserva seu valor atual. As variantes de servidor compartilham um conjunto de campos, e um campo que o tipo armazenado não possui é aceito e descartado.

Campo	Tipo	Descrição
name?¹	?string	O nome do canal (1-100 caracteres após normalização)
topic?²	?string	O tópico do canal (1-1.024 caracteres), ou null para limpá-lo
url?³	?string	O destino de um canal de link de servidor (1-2.048 caracteres, `http` ou `https`), ou null para limpá-lo
parent_id?⁴	?snowflake	O ID da categoria pai, onde null ou o snowflake `0` move o canal para o nível superior
bitrate?⁵¹³	?integer	A taxa de bits de voz em bits por segundo (8.000-384.000)
user_limit?⁵	?integer	O limite de ocupação de voz (0-99, onde `0` configura sem limite)
voice_connection_limit?⁵	?integer	O número de conexões de voz simultâneas que um usuário pode manter (1-100)
permission_overwrites?⁶	array[substituição de permissão object]	A coleção completa de substituições que substitui a armazenada
nsfw_override?⁷	?boolean	Se este canal sobrepõe a restrição de idade herdada
nsfw?⁸	?boolean	Se o canal é restrito por idade, um switch legado substituído por `nsfw_override`
content_warning_level?⁹	integer	O nível de aviso de conteúdo a armazenar neste canal
content_warning_text?¹⁰	?string	O texto de aviso de conteúdo (máx. 200 caracteres)
rate_limit_per_user?¹¹	?integer	O intervalo de modo lento em segundos (0-21.600) para canal de texto ou voz de servidor
rtc_region?¹²	?string	O ID da região RTC (1-64 caracteres) para canal de voz de servidor, onde null seleciona roteamento automático

¹ Um null explícito preserva o nome atual. Em um servidor sem nomes de canais flexíveis, o Decoding Chat converte o nome de um canal de texto de servidor para minúsculas, substitui espaços por hífens e remove pontuação não permitida

² Um null explícito limpa o tópico armazenado

³ Aplicado apenas a um canal de link de servidor. Um null explícito limpa o destino

⁴ Uma categoria rejeita qualquer pai com CATEGORIES_CANNOT_HAVE_PARENTS

⁵ Aplicado apenas a um canal de voz de servidor, e um null explícito limpa o valor armazenado

⁶ Cada entrada possui id, type e as máscaras opcionais allow e deny, cada uma com padrão 0

⁷ Um null explícito faz o canal voltar a herdar de sua categoria pai e depois do servidor

⁸ nsfw_override prevalece quando ambos forem fornecidos. Sozinho, true mapeia para nsfw_override true e false mapeia para null

⁹ Apenas 0 e 1 são aceitos, e 0 retorna o canal para herança

¹⁰ Removido espaços. Um valor vazio após remoção de espaços, ou um null explícito, limpa o texto armazenado

¹¹ Aplicado apenas a canal de texto ou voz de servidor. Um null explícito preserva o intervalo atual

¹² Aplicado apenas a canal de voz de servidor. Fornecer o campo, inclusive como null, requer UPDATE_RTC_REGION

¹³ O valor armazenado é limitado a 96.000 a menos que o servidor possua o recurso de taxa de bits de áudio. Um valor mais alto é armazenado no limite em vez de ser rejeitado

Uma url que não seja uma URL absoluta http ou https com host retorna 400 INVALID_FORM_BODY com o código INVALID_URL_FORMAT no caminho url.

Um pai que não existe no mesmo servidor retorna 400 INVALID_FORM_BODY com o código INVALID_PARENT_CHANNEL no caminho parent_id. Um pai que não seja uma categoria retorna PARENT_MUST_BE_CATEGORY da mesma forma.

Nomear uma categoria diferente da pai atual também verifica a capacidade. Uma categoria cheia retorna 400 MAX_CATEGORY_CHANNELS com o limite atingido, que é o limite max_channels_per_category da implantação e tem padrão de 50.

O Decoding Chat aceita uma máscara de substituição como string decimal ou como inteiro JSON. A string decimal aceita no máximo 9223372036854775807, e uma maior retorna 400 INVALID_FORM_BODY com o código INTEGER_OUT_OF_INT64_RANGE. O inteiro JSON aceita no máximo 9007199254740991, e um número fora da faixa de inteiros seguros retorna INVALID_INTEGER_FORMAT. Todos os bits fora do conjunto de permissões definido são descartados.

Um rtc_region não nulo nomeia uma região que Listar regiões RTC retorna para este servidor. Qualquer outro valor retorna 400 INVALID_FORM_BODY com o código INVALID_OR_RESTRICTED_RTC_REGION no caminho rtc_region. Uma implantação que não configura topologia de voz não valida nenhuma região e armazena qualquer string aceita.

Corpo para mensagem direta em grupo

Todos os campos são opcionais, e um campo omitido preserva seu valor atual.

Campo	Tipo	Descrição
name?	?string	O nome do grupo (1-100 caracteres após normalização), ou null para limpá-lo
icon?¹	?base64 string	A imagem de ícone codificada em base64 (no máximo 13.981.014 caracteres codificados), ou null para limpá-la
owner_id?²	?snowflake	O ID do novo proprietário
nicks?³	?map[snowflake, ?string]	Os apelidos com chave pelo ID decimal do usuário (cada 0-32 caracteres, ou null)

¹ Base64 puro ou URL de dados, com 1 a 13.981.014 caracteres após o prefixo

² Um null explícito não solicita transferência. O chamador deve ser o proprietário atual e o alvo um destinatário atual

³ Um null explícito limpa todos os apelidos e requer propriedade. Um não-proprietário pode alterar apenas sua própria chave

Os bytes decodificados do ícone são no máximo o limite avatar_max_size configurado na instância, que tem padrão de 10 MiB (10485760 bytes). Uma imagem maior é rejeitada no caminho icon com o código IMAGE_SIZE_EXCEEDS_LIMIT. PNG, JPEG, WebP, GIF, APNG, AVIF, HEIC, HEIF, JXL e SVG são aceitos, e um AVIF animado é rejeitado no mesmo caminho com INVALID_IMAGE_FORMAT.

Um owner_id nomeando uma conta que não é destinatária atual retorna 404 UNKNOWN_USER. Um alvo bot retorna 400 CANNOT_TRANSFER_OWNERSHIP_TO_BOT.

O Decoding Chat remove espaços de um apelido armazenado, e um valor null ou vazio após a remoção limpa esse apelido individual. Uma chave em nicks que não seja um destinatário atual nem o chamador retorna 404 UNKNOWN_USER.

Resposta

Status	Corpo	Condição
200	canal object	O canal foi modificado, ou os valores enviados já correspondiam ao estado armazenado
403	resposta de erro	Uma permissão requerida, propriedade ou autoridade de bits de permissão está ausente e a requisição retorna `MISSING_PERMISSIONS`
403	resposta de erro	Uma alteração concorrente removeu o chamador da mensagem direta em grupo e a requisição retorna `MISSING_ACCESS`
403	resposta de erro	O servidor existe, mas o estado de membro do chamador não pode ser resolvido e a requisição retorna `ACCESS_DENIED`
403	resposta de erro	A restrição de idade resolvida não foi satisfeita e a requisição retorna `NSFW_CONTENT_AGE_RESTRICTED`
404	resposta de erro	O canal não existe, ou o chamador não é destinatário da mensagem direta em grupo, cada um retornando `UNKNOWN_CHANNEL`
404	resposta de erro	O servidor proprietário do canal não existe e a requisição retorna `UNKNOWN_GUILD`
404	resposta de erro	Um proprietário ou alvo de apelido referenciado não é um destinatário atual e a requisição retorna `UNKNOWN_USER`

Efeitos colaterais

Uma alteração em canal de servidor emite Channel Update para todas as sessões inscritas no servidor. Substituir as substituições de permissão de uma categoria também as substitui em cada canal filho cujas substituições correspondam exatamente aos valores anteriores da categoria, com um Dispatch por filho alterado. Um filho cujas substituições diferiam permanece inalterado.

Alterar rate_limit_per_user limpa a contagem regressiva de modo lento restante de todos os usuários no canal, para que a próxima mensagem de cada usuário seja verificada contra o novo intervalo. Alterar rtc_region em um canal de voz de servidor move suas conexões de voz ativas para a região selecionada.

Uma requisição que altera pelo menos um campo cria uma entrada de log de auditoria de atualização de canal com o motivo fornecido. Enviar permission_overwrites também cria uma entrada de log de auditoria de criação, atualização ou exclusão de substituição para cada substituição que o array adicionar, alterar ou remover.

Uma alteração em mensagem direta em grupo emite Channel Update para todos os destinatários atuais. Uma alteração de nome ou de ícone bem-sucedida cria uma mensagem de sistema entregue com Message Create, e substituir o ícone exclui permanentemente o anterior. Alterações de propriedade e apelido não criam mensagem de sistema nem entrada de auditoria.

Rate limit

20 requisições por 10 segundos para cada usuário autenticado e ID de canal, no bucket channel:update::channel_id.

Excluir ou sair do canal

DELETE/v1/channels/{channel_id}

Bot Audit reason

Exclui um canal de servidor, fecha uma mensagem direta ou remove o chamador de uma mensagem direta em grupo. Retorna 204 com um corpo vazio. Emite um evento de Gateway Channel Delete.

Limitações

Excluir um canal de servidor requer VIEW_CHANNEL e MANAGE_CHANNELS.
Fechar uma mensagem direta ou sair de uma mensagem direta em grupo requer acesso de destinatário atual.
O canal de notas pessoais não pode ser excluído, e a requisição retorna 400 CANNOT_EXECUTE_ON_DM.
Definir delete_messages também requer modo sudo para uma sessão de usuário, satisfeito por um comprovante sudo válido ou pelos campos de verificação no corpo. Um token de bot sempre o satisfaz.

MANAGE_CHANNELS é uma permissão elevada. Ela também requer um autenticador multifator registrado quando o nível MFA do servidor é elevado e o chamador não é o proprietário do servidor. Um chamador que possui a permissão sem esse autenticador recebe 400 TWO_FACTOR_REQUIRED. O requisito de sudo em delete_messages aplica-se em todos os níveis MFA de servidor.

Parâmetros de caminho

Campo	Tipo	Descrição
channel_id	snowflake	O ID do canal a excluir, fechar ou sair

Parâmetros de consulta

Campo	Tipo	Descrição
silent?¹	boolean	Se deve suprimir a mensagem de sistema de saída de uma mensagem direta em grupo (padrão false)
delete_messages?¹	boolean	Se deve excluir as mensagens do próprio chamador neste canal primeiro (padrão false)

¹ Apenas os valores exatos sem espaços true, True e 1 são verdadeiros. Um parâmetro ausente e qualquer outro valor, incluindo TRUE e yes, são falsos

Cabeçalhos da requisição

Campo	Tipo	Descrição
X-Fluxer-Sudo-Mode-JWT?¹	string	Um comprovante de modo sudo existente, lido quando `delete_messages` é definido

¹ Um comprovante aceito é retornado no mesmo cabeçalho de resposta, e concluir o fluxo MFA emite um novo

Corpo JSON

O corpo é opcional. O Decoding Chat o lê apenas quando delete_messages está definido e nenhum comprovante sudo existente satisfaz o requisito.

Campo	Tipo	Descrição
password?¹	string	A senha da conta, oferecida como comprovante sudo
mfa_method?²	string	O método de verificação, `totp` ou `webauthn`
mfa_code?	string	O código do autenticador (1-32 caracteres), fornecido com o método `totp`
webauthn_response?	assercão WebAuthn object	A asserção WebAuthn para verificação sudo
webauthn_challenge?	string	O desafio (1-256 caracteres) vinculado à asserção de modo sudo

¹ Aceito apenas para uma conta sem segundo fator configurado. Uma senha rejeitada retorna 400 INVALID_FORM_BODY com o código INVALID_PASSWORD no caminho password

² Aceito apenas para uma conta com segundo fator configurado. Um código ou asserção rejeitada retorna 400 INVALID_FORM_BODY com o código INVALID_MFA_CODE no caminho mfa_code

Uma conta que não armazena senha nem segundo fator é verificada sem nenhum comprovante.

Resposta

Status	Corpo	Condição
204	vazio	O canal foi excluído, fechado ou deixado
400	resposta de erro	O alvo é o canal de notas pessoais e a requisição retorna `CANNOT_EXECUTE_ON_DM`
403	resposta de erro	O chamador não é membro do servidor ou não possui `VIEW_CHANNEL` ou `MANAGE_CHANNELS`, cada um retornando `MISSING_PERMISSIONS`
403	resposta de erro	Verificação sudo é necessária e a requisição retorna `SUDO_MODE_REQUIRED`
403	resposta de erro	Uma alteração concorrente removeu o chamador da mensagem direta em grupo e a requisição retorna `MISSING_ACCESS`
403	resposta de erro	O servidor existe, mas o estado de membro do chamador não pode ser resolvido e a requisição retorna `ACCESS_DENIED`
403	resposta de erro	A restrição de idade resolvida não foi satisfeita e a requisição retorna `NSFW_CONTENT_AGE_RESTRICTED`
404	resposta de erro	O canal não existe, ou o chamador não é destinatário do canal privado, cada um retornando `UNKNOWN_CHANNEL`, ou o servidor proprietário do canal não existe e a requisição retorna `UNKNOWN_GUILD`

Efeitos colaterais

Excluir uma categoria de servidor primeiro limpa o parent_id de cada canal filho e emite Channel Update para cada um. A própria categoria é então excluída como qualquer outro canal de servidor.

Excluir um canal de servidor remove permanentemente suas mensagens, anexos, convites e webhooks. Os inscritos do servidor recebem Channel Delete, e a exclusão aparece no log de auditoria. Quando o canal excluído é o canal de sistema, regras ou AFK do servidor, o Decoding Chat limpa essa configuração do servidor e emite Guild Update.

Fechar uma mensagem direta marca o canal fechado apenas para o chamador e emite Channel Delete para aquele chamador. O canal, suas mensagens e a visualização do outro destinatário permanecem intocados.

Sair de uma mensagem direta em grupo remove o chamador do conjunto de destinatários, remove o apelido do chamador e fecha o canal para o chamador. Se o chamador era proprietário do grupo, a propriedade é transferida para um dos destinatários restantes escolhido aleatoriamente.

Os destinatários restantes recebem Channel Recipient Remove e, a menos que silent seja verdadeiro, também uma mensagem de sistema de remoção via Message Create. O chamador que sai recebe Channel Delete. Nenhum Channel Update reporta a transferência de propriedade ou o apelido removido, portanto um cliente que rastreia owner_id ou nicks deve rebuscar o canal.

Sair como o último destinatário exclui permanentemente as mensagens do canal e o registro do canal, sem mensagem de sistema.

Definir delete_messages exclui as mensagens de autoria do chamador neste canal após a verificação sudo e antes da operação do canal ser executada, e a resposta aguarda essa exclusão ser concluída.

Rate limit

20 requisições por 10 segundos para cada usuário autenticado e ID de canal, no bucket channel:delete::channel_id.

Adicionar destinatário em mensagem direta em grupo

PUT/v1/channels/{channel_id}/recipients/{user_id}

Bot

Adiciona um usuário a uma mensagem direta em grupo e retorna 204 com um corpo vazio. Emite um evento de Gateway Channel Recipient Add.

Limitações

O chamador deve ser um destinatário atual do grupo e deve ser amigo do alvo, inclusive quando o chamador for um bot.
A política de admissão de mensagens diretas em grupo do alvo deve permitir o chamador.
Uma instância com CAPTCHA habilitado também requer um comprovante de CAPTCHA.

O Decoding Chat avalia a política de admissão do alvo nesta ordem:

Um alvo que nunca armazenou configurações admite qualquer chamador.
A configuração de ninguém rejeita qualquer chamador, e a configuração de todos admite qualquer chamador.
A configuração apenas amigos admite apenas um chamador que o alvo possui como amigo.
Caso contrário, o Decoding Chat admite o chamador por meio de uma amizade existente, depois por um amigo em comum quando a configuração de amigos de amigos estiver habilitada, e depois por um servidor em comum quando a configuração de membros do servidor estiver habilitada.

Parâmetros de caminho

Campo	Tipo	Descrição
channel_id	snowflake	O ID do canal de mensagem direta em grupo
user_id	snowflake	O ID do usuário a adicionar

Cabeçalhos da requisição

Campo	Tipo	Descrição
X-Captcha-Token?¹	string	Um comprovante de CAPTCHA
X-Captcha-Type?²	string	O provedor de CAPTCHA, `hcaptcha` ou `turnstile`

¹ Um comprovante ausente retorna 400 CAPTCHA_REQUIRED e um comprovante rejeitado retorna 400 INVALID_CAPTCHA, assim como um comprovante para um provedor para o qual a instância não possui chave secreta. CAPTCHA informa quando uma instância pula a verificação

² hcaptcha ou turnstile seleciona esse provedor independentemente da instância o ter configurado ou não. O provedor configurado da instância é usado quando o cabeçalho estiver ausente ou tiver qualquer outro valor

Resposta

Status	Corpo	Condição
204	vazio	Destinatário foi adicionado, ou já era destinatário
400	resposta de erro	Comprovante de CAPTCHA ausente ou rejeitado, ou o chamador e o alvo não são amigos e a requisição retorna `NOT_FRIENDS_WITH_USER`
400	resposta de erro	O grupo já está cheio e a requisição retorna `MAX_GROUP_DM_RECIPIENTS`
400	resposta de erro	O canal não é uma mensagem direta em grupo e a requisição retorna `INVALID_CHANNEL_TYPE`
403	resposta de erro	O chamador não é destinatário, ou a política de admissão do alvo rejeita o chamador, cada um retornando `MISSING_ACCESS`
404	resposta de erro	O canal não existe e a requisição retorna `UNKNOWN_CHANNEL`

O corpo de MAX_GROUP_DM_RECIPIENTS possui max_recipients, o limite exato que foi atingido. Esse limite é o limite max_group_dm_recipients da implantação resolvido para o chamador, e tem padrão de 50.

Efeitos colaterais

O usuário adicionado recebe Channel Create, os destinatários existentes recebem Channel Recipient Add, e todos os destinatários recebem uma mensagem de sistema de adição via Message Create. Adicionar um destinatário existente não altera nada e não emite Dispatch.

Rate limit

20 requisições por 10 segundos para cada usuário autenticado e ID de canal, no bucket channel:update::channel_id. O bucket de proteção user:group_dm:recipient:add adiciona 10 requisições por hora para cada usuário autenticado, e não consome o limite global.

Remover destinatário de mensagem direta em grupo

DELETE/v1/channels/{channel_id}/recipients/{user_id}

Bot

Remove um usuário de uma mensagem direta em grupo e retorna 204 com um corpo vazio. Emite um evento de Gateway Channel Recipient Remove.

Limitações

O chamador deve ser um destinatário atual.
Um chamador pode se remover independentemente da propriedade.
Remover outro destinatário requer a propriedade do grupo.
Definir delete_messages entra em vigor apenas quando user_id for o chamador, e requer verificação sudo nos mesmos termos de Excluir ou sair do canal.

Parâmetros de caminho

Campo	Tipo	Descrição
channel_id	snowflake	O ID do canal de mensagem direta em grupo
user_id	snowflake	O ID do destinatário a remover

Parâmetros de consulta

Campo	Tipo	Descrição
silent?¹	boolean	Se deve suprimir a mensagem de sistema de remoção de destinatário (padrão false)
delete_messages?¹	boolean	Se deve excluir as mensagens do próprio chamador neste canal antes da auto-remoção (padrão false)

¹ Apenas os valores exatos sem espaços true, True e 1 são verdadeiros. Um parâmetro ausente e qualquer outro valor, incluindo TRUE e yes, são falsos

Cabeçalhos da requisição

Campo	Tipo	Descrição
X-Fluxer-Sudo-Mode-JWT?¹	string	Um comprovante de modo sudo existente, lido quando `delete_messages` é definido para auto-remoção

¹ Um comprovante aceito é retornado no mesmo cabeçalho de resposta, e concluir o fluxo MFA emite um novo

Corpo JSON

O corpo opcional possui os mesmos campos de verificação sudo de Excluir ou sair do canal. O Decoding Chat o lê apenas quando uma auto-remoção define delete_messages e a requisição não possui comprovante sudo existente.

Resposta

Status	Corpo	Condição
204	vazio	O destinatário foi removido
400	resposta de erro	O canal não é uma mensagem direta em grupo e a requisição retorna `INVALID_CHANNEL_TYPE`, ou o alvo não é destinatário e a requisição retorna `INVALID_FORM_BODY` com o código `USER_NOT_IN_CHANNEL`
403	resposta de erro	O chamador não é destinatário e a requisição retorna `MISSING_ACCESS`
403	resposta de erro	O chamador não é o proprietário ao remover outro destinatário e a requisição retorna `MISSING_PERMISSIONS`
403	resposta de erro	Verificação sudo é necessária e a requisição retorna `SUDO_MODE_REQUIRED`
404	resposta de erro	O canal não existe e a requisição retorna `UNKNOWN_CHANNEL`

Efeitos colaterais

A remoção fecha o canal para o destinatário e limpa seu apelido. Se ele era proprietário do grupo, a propriedade é transferida para um destinatário restante selecionado aleatoriamente, como em Excluir ou sair do canal.

O destinatário removido recebe Channel Delete. Os destinatários restantes recebem Channel Recipient Remove, e a mensagem de sistema de remoção via Message Create a menos que silent seja verdadeiro. Nenhum Channel Update reporta a transferência de propriedade ou o apelido removido.

Remover o último destinatário exclui permanentemente as mensagens do canal, as remove das pesquisas e exclui o registro do canal, sem mensagem de sistema. Definir delete_messages em uma auto-remoção exclui as mensagens do chamador neste canal antes que a remoção seja executada.

Rate limit

20 requisições por 10 segundos para cada usuário autenticado e ID de canal, no bucket channel:update::channel_id.

Definir substituição de permissão no canal

PUT/v1/channels/{channel_id}/permissions/{overwrite_id}

Bot Audit reason

Cria ou substitui uma substituição de permissão em um canal de servidor e retorna 204 com um corpo vazio. Requer MANAGE_ROLES naquele canal. Emite um evento de Gateway Channel Update.

Limitações

Um chamador sem ADMINISTRATOR não pode permitir um bit de permissão fora de suas próprias permissões efetivas naquele canal, e nem remover um bit negado fora delas.

A operação não requer VIEW_CHANNEL e nunca retorna TWO_FACTOR_REQUIRED ou NSFW_CONTENT_AGE_RESTRICTED.

Parâmetros de caminho

Campo	Tipo	Descrição
channel_id	snowflake	O ID do canal do servidor
overwrite_id	snowflake	O ID do cargo ou membro que a substituição representa

Cabeçalhos da requisição

Campo	Tipo	Descrição
X-Fluxer-Features?¹	string	Uma declaração de recurso separada por vírgula

¹ Um bit restrito por recurso que a declaração não nomeia é copiado da substituição armazenada, portanto a requisição não pode defini-lo nem limpá-lo

Corpo JSON

Campo	Tipo	Descrição
type¹	integer	O tipo de substituição de permissão de `overwrite_id`
allow?²	?decimal string	O bitfield de permissões a permitir (padrão `0`)
deny?²	?decimal string	O bitfield de permissões a negar (padrão `0`)

¹ Apenas 0 e 1 são aceitos

² Uma string decimal de no máximo 9223372036854775807, ou um inteiro JSON de no máximo 9007199254740991. Um valor omitido ou null é tratado como 0

Uma string decimal maior retorna 400 INVALID_FORM_BODY com o código INTEGER_OUT_OF_INT64_RANGE. Um número JSON fora da faixa de inteiros seguros retorna INVALID_INTEGER_FORMAT, assim como uma string que não contenha apenas dígitos. Todos os bits fora do conjunto de permissões definido são descartados antes da verificação de autoridade e antes que a alteração seja aplicada.

Resposta

Status	Corpo	Condição
204	vazio	Substituição foi criada ou substituída
403	resposta de erro	`MANAGE_ROLES` no canal ou autoridade de bit de permissão está ausente, cada um retornando `MISSING_PERMISSIONS`
404	resposta de erro	O canal não existe, ou não é um canal de servidor, cada um retornando `UNKNOWN_CHANNEL`

Efeitos colaterais

O Decoding Chat emite Channel Update para todas as sessões inscritas no servidor, inclusive quando a substituição enviada corresponder exatamente à armazenada. Quando o canal for uma categoria, cada filho cujas substituições correspondam exatamente aos valores anteriores da categoria recebe uma cópia das novas substituições da categoria e seu próprio Channel Update.

A operação registra uma entrada de auditoria de criação ou atualização de substituição com o motivo fornecido. Uma substituição inalterada não registra entrada de auditoria.

Rate limit

20 requisições por 10 segundos para cada usuário autenticado e ID de canal, no bucket channel:update::channel_id.

Excluir substituição de permissão no canal

DELETE/v1/channels/{channel_id}/permissions/{overwrite_id}

Bot Audit reason

Exclui uma substituição de permissão de um canal de servidor e retorna 204 com um corpo vazio. Requer MANAGE_ROLES naquele canal. Emite um evento de Gateway Channel Update.

Limitações

Um chamador sem ADMINISTRATOR deve possuir todas as permissões que a substituição removida negava.

A operação é idempotente, não requer VIEW_CHANNEL e nunca retorna TWO_FACTOR_REQUIRED ou NSFW_CONTENT_AGE_RESTRICTED.

Parâmetros de caminho

Campo	Tipo	Descrição
channel_id	snowflake	O ID do canal do servidor
overwrite_id¹	snowflake	O ID do cargo ou membro que a substituição representa

¹ O identificador sozinho seleciona a substituição, e a requisição não possui tipo de substituição

Resposta

Status	Corpo	Condição
204	vazio	A substituição foi excluída, ou nenhuma substituição existia para o identificador
403	resposta de erro	`MANAGE_ROLES` no canal ou autoridade de bit de permissão está ausente, cada um retornando `MISSING_PERMISSIONS`
404	resposta de erro	O canal não existe, ou não é um canal de servidor, cada um retornando `UNKNOWN_CHANNEL`

Efeitos colaterais

O Decoding Chat emite Channel Update para todas as sessões inscritas no servidor, inclusive quando o identificador não nomear nenhuma substituição existente. Remover uma substituição existente também registra uma entrada de auditoria de exclusão de substituição com o estado anterior da substituição e o motivo fornecido. Um identificador que não nomeia nenhuma substituição existente não registra entrada de auditoria. Quando o canal alvo for uma categoria, cada filho cujas substituições correspondam exatamente às substituições anteriores da categoria recebe uma cópia das novas substituições da categoria e seu próprio Channel Update.

Rate limit

20 requisições por 10 segundos para cada usuário autenticado e ID de canal, no bucket channel:update::channel_id.