Canais privados

Um canal privado é uma conversa fora de qualquer guilda. É uma mensagem direta entre duas contas ou uma DM de grupo com seu próprio conjunto de participantes. Seus campos vêm do objeto de canal.

As rotas aqui recebem uma sessão de usuário ou um token de bot. Uma credencial bearer OAuth2 recebe 403 ACCESS_DENIED, e uma conta com uma ação obrigatória pendente recebe 403 ACCOUNT_SUSPICIOUS_ACTIVITY.

O estado aberto é por participante

Um canal de mensagem direta existe uma vez, e cada participante mantém seu próprio estado aberto. Fechar um lado deixa o canal e suas mensagens no lugar, de modo que uma solicitação posterior Criar canal privado para o mesmo par retorna aquele canal armazenado.

Objeto de mensagens pré-carregadas

A resposta de ambas as operações de pré-carregamento. Não possui conjunto fixo de campos, e o nome de cada propriedade é o snowflake de um canal solicitado.

Estrutura

Campo	Tipo	Descrição
{channel_id}12	?objeto mensagem	A última mensagem que o chamador pode ler no canal, ou null

¹ Um canal solicitado que não é nem uma mensagem direta nem uma DM de grupo não possui nenhuma propriedade. Um canal que não pode ser resolvido, ou cuja última mensagem está ausente, está presente com o valor null

² Um ID de canal repetido se contrai em uma única propriedade, portanto, o objeto contém no máximo uma entrada para cada ID distinto

Objeto de destinatário não adicionável de DM de grupo

Um destinatário que não pôde ser adicionado a uma DM de grupo e o motivo. Criar canal privado retorna um array destes como unaddable_recipients no nível superior de uma resposta de erro GROUP_DM_RECIPIENTS_NOT_ADDABLE.

Estrutura

Campo	Tipo	Descrição
user_id	snowflake	O destinatário que não pôde ser adicionado
reason	string	O motivo de não adicionável pelo qual o destinatário foi rejeitado

Motivos não adicionáveis de DM de grupo

Valor	Nome	Descrição
unknown_user	Usuário desconhecido	O destinatário não resolve
not_friends	Não amigos	O chamador é uma conta comum e não possui amizade com o destinatário
blocked1	Bloqueado	O chamador é uma conta de bot e não compartilha guilda com o destinatário
group_dm_add_disabled	Adição de DM de grupo desativada	As flags de permissão de adição de DM de grupo do destinatário rejeitam o chamador

¹ Relatado apenas no caminho do bot. O caminho comum relata uma amizade ausente como not_friends

Listar canais privados

GET/v1/users/@me/channelsBot

Retorna os objetos de canal de mensagem direta e DM de grupo abertos do chamador.

Uma mensagem direta fechada está ausente, mesmo que o canal e seu histórico ainda existam. A resposta não tem garantia de ordem e não é paginada. O canal de notas pessoais do chamador nunca é retornado.

Cada canal retornado tem seus destinatários com o chamador removido, de modo que uma mensagem direta mantém exatamente um destinatário e uma DM de grupo um a menos que a contagem de participantes. Uma DM de grupo cujo único participante é o chamador omite a chave recipients inteiramente.

O Decoding Chat omite uma entrada aberta cujo canal não lista mais o chamador entre seus destinatários, de modo que sair de uma DM de grupo não requer uma chamada de limpeza separada.

Resposta

Status	Corpo	Condição
200	array[objeto de canal]	Os canais privados abertos foram retornados

Limite de taxa

40 requisições por 10 segundos para cada usuário autenticado, no bucket user:channels, compartilhado com Criar canal privado, Fixar canal privado e Desafixar canal privado.

Criar canal privado

POST/v1/users/@me/channelsBot

Abre uma mensagem direta com uma conta ou cria uma DM de grupo. Retorna um objeto de canal em caso de sucesso. Emite os eventos Gateway Channel Create e Message Create.

Um campo do corpo seleciona o tipo de canal. recipient_id abre uma mensagem direta. recipients sempre cria uma DM de grupo, independentemente de seu comprimento. Um array de um único elemento cria uma DM de grupo com dois participantes, e um array vazio cria uma DM de grupo cujo único participante é o chamador.

Uma solicitação fornecendo recipients também consome o bucket user:group_dm:create e está sujeita à verificação de CAPTCHA abaixo, seja qual for a contagem de participantes resultante.

Quando a política da comunidade da instância define direct_messages_disabled como true, todas as solicitações retornam 400 DIRECT_MESSAGES_DISABLED após a validação do corpo e a aplicação do bucket de DM de grupo e do CAPTCHA.

Uma conta não reivindicada não possui senha e não chegou pelo SSO. O Decoding Chat rejeita um chamador não reivindicado com 400 UNCLAIMED_ACCOUNT_CANNOT_JOIN_GROUP_DMS quando recipients é fornecido, e com 400 UNCLAIMED_ACCOUNT_CANNOT_SEND_DIRECT_MESSAGES caso contrário. Um chamador comum, então, precisa de um endereço de email verificado, caso contrário a solicitação retorna 403 DIRECT_MESSAGE_EMAIL_VERIFICATION_REQUIRED. Um chamador de bot está isento do requisito de email e nunca é não reivindicado.

Admissão de mensagem direta

Uma solicitação nomeando o chamador como seu próprio alvo retorna 400 CANNOT_DM_YOURSELF como o código de campo em recipient_id em INVALID_FORM_BODY. Um alvo não resolvido retorna 404 UNKNOWN_USER.

O Decoding Chat não lê nenhum estado de bloqueio, nenhuma amizade e nenhuma guilda compartilhada nesta rota. Um alvo que resolve é admitido, então o chamador abre uma mensagem direta com uma conta que o bloqueou. CANNOT_SEND_MESSAGES_TO_USER é alcançável apenas a partir de Criar mensagem, o que aplica a política de mensagens diretas do destinatário a cada envio.

Bloquear não remove nenhum canal da conta bloqueada

Bloquear não fecha nenhum canal existente. A conta bloqueada ainda abre a mensagem direta do par através desta rota e recebe 200. Apenas o envio é recusado, com 400 CANNOT_SEND_MESSAGES_TO_USER.

Um chamador SPAMMER recebe um canal que ninguém vê

Um chamador comum com a flag SPAMMER nunca abre uma mensagem direta compartilhada. Um alvo não resolvido retorna 404 UNKNOWN_USER, e qualquer outro retorna 200 com um canal que existe apenas para o chamador. Nenhum Dispatch chega ao alvo.

Admissão de DM de grupo

O conjunto de participantes, ou seja, os destinatários fornecidos mais o chamador, permanece dentro do limite max_group_dm_recipients da instância resolvido para o chamador, cujo padrão é 50. Ultrapassá-lo retorna 400 MAX_GROUP_DM_RECIPIENTS com o teto aplicado no membro de nível superior max_recipients. recipients é limitado a 49 elementos antes de o limite ser lido, portanto, um limite de instância aumentado não aumenta o teto efetivo.

Um ID duplicado em recipients retorna 400 DUPLICATE_RECIPIENTS_NOT_ALLOWED, e o próprio ID do chamador dentro dele retorna 400 CANNOT_ADD_YOURSELF_TO_GROUP_DM. Ambos são códigos de campo em recipients sob INVALID_FORM_BODY.

Cada participante, incluindo o chamador, detém menos DMs de grupo abertas do que o limite max_group_dms_per_user da instância resolvido para essa conta, cujo padrão é 150. Um participante no limite faz a solicitação retornar 400 MAX_GROUP_DMS com o teto aplicado no membro de nível superior max_group_dms.

O Decoding Chat avalia cada outro destinatário de forma independente e coleta cada falha, usando os motivos não adicionáveis acima. Um destinatário reprovado rejeita a solicitação inteira com 400 GROUP_DM_RECIPIENTS_NOT_ADDABLE. A resposta tem as entradas rejeitadas no membro de nível superior unaddable_recipients e os IDs de usuário aceitos em addable_recipients, para que o chamador possa tentar novamente com um conjunto menor.

Um chamador comum não pode adicionar um destinatário que ele bloqueou ou um destinatário que o bloqueou. Bloquear exclui a amizade em ambas as contas, e uma solicitação de amizade entre as duas contas não cria uma nova amizade enquanto houver bloqueio.

A admissão em DM de grupo não lê estado de bloqueio

O Decoding Chat não exige amizade para um chamador de bot. Um destinatário que bloqueou o bot é adicionado quando ambos compartilham uma guilda e as flags de permissão de adição de DM de grupo do destinatário o admitem.

Cabeçalhos de solicitação

Campo	Tipo	Descrição
X-Captcha-Token?1	string	A prova CAPTCHA
X-Captcha-Type?2	string	O provedor CAPTCHA, seja hcaptcha ou turnstile

¹ Lido apenas em uma solicitação fornecendo recipients, em que uma prova ausente retorna 400 CAPTCHA_REQUIRED e uma prova rejeitada retorna 400 INVALID_CAPTCHA, assim como uma prova para um provedor para o qual a instância não possui a chave secreta. CAPTCHA informa quando uma instância pula a verificação

² O valor hcaptcha ou turnstile seleciona esse provedor, independentemente de a instância o ter configurado ou não. O provedor configurado da instância é usado quando o cabeçalho está ausente ou tem qualquer outro valor

Corpo JSON

Campo	Tipo	Descrição
recipient_id?1	snowflake	O único destinatário de uma mensagem direta
recipients?1	array[snowflake]	Os outros participantes de uma DM de grupo, excluindo o chamador (máx. 49)

¹ Exatamente um dos dois é fornecido. Fornecer ambos ou nenhum deles falha na validação do corpo com o caminho de entrada root

Resposta

Status	Corpo	Condição
200	objeto de canal	A mensagem direta foi aberta ou a DM de grupo foi criada
400	resposta de erro	CAPTCHA, elegibilidade da conta, conjunto de destinatários, política de relacionamento, limite de DM de grupo ou política de instância rejeita a criação
403	resposta de erro	O endereço de email de um chamador comum não foi verificado e a solicitação retorna DIRECT_MESSAGE_EMAIL_VERIFICATION_REQUIRED
404	resposta de erro	O chamador ou o destinatário da mensagem direta não resolve

Efeitos colaterais

Uma mensagem direta recém-criada abre apenas para o chamador e emite Channel Create para o chamador. O lado do destinatário permanece fechado até que ele próprio o abra, ou até que a dupla se torne amiga através de Aceitar solicitação ou bloquear usuário, o que abre ambos os lados. Reabrir uma mensagem direta existente sempre emite CHANNEL_CREATE para o chamador.

Criar uma DM de grupo torna o chamador seu proprietário, adiciona o conjunto completo de participantes e emite Channel Create para cada participante. Ela cria uma mensagem do sistema RECIPIENT_ADD com autoria do chamador para cada outro destinatário e emite Message Create para cada uma a todos os participantes. A criação inicial não emite Channel Recipient Add, que é reservado para um destinatário adicionado posteriormente. Uma DM de grupo criada a partir de um array recipients vazio não produz mensagem do sistema.

Limite de taxa

40 requisições por 10 segundos para cada usuário autenticado, no bucket user:channels, compartilhado com Listar canais privados, Fixar canal privado e Desafixar canal privado.

Uma solicitação fornecendo recipients também consome o bucket user:group_dm:create de 10 solicitações por hora para cada usuário autenticado, que está isento do limite global HTTP.

Pré-carregar mensagens de canais privados

POST/v1/users/@me/preload-messagesBot

Retorna o objeto de mensagens pré-carregadas contendo a última mensagem legível de cada canal privado solicitado.

O Decoding Chat resolve cada canal solicitado de forma independente e reporta um canal desconhecido, uma permissão ausente ou uma mensagem ausente como null para aquele canal. A solicitação ainda responde 200. Ele aplica a mesma autorização de leitura que o histórico de mensagens comum. Um canal que o chamador não consegue ver é indistinguível de um cujo histórico está vazio.

Corpo JSON

Campo	Tipo	Descrição
channels1	array[snowflake]	Os canais privados para pré-carregar (máx. 100)

¹ Obrigatório. Um array vazio é aceito e retorna um objeto vazio, e mais de 100 elementos falham na validação do corpo antes que qualquer canal seja lido

Resposta

Status	Corpo	Condição
200	objeto de mensagens pré-carregadas	Os canais solicitados foram resolvidos

Efeitos colaterais

Esta leitura não confirma nenhuma mensagem e não altera o estado de leitura do chamador. O próprio ID de usuário do chamador é o ID de seu canal de notas pessoais, e resolvê-lo cria a linha desse canal quando a conta não o possui. O canal de notas não é nem uma mensagem direta nem uma DM de grupo, portanto, a resposta não possui propriedade para ele.

Limite de taxa

40 requisições por 10 segundos para cada usuário autenticado, no bucket user:preload_messages, compartilhado com Pré-carregar mensagens de canais privados por apelido.

Pré-carregar mensagens de canais privados por apelido

POST/v1/users/@me/channels/messages/preloadBot

Um apelido de Pré-carregar mensagens de canais privados. O corpo da solicitação, a resposta, a autorização e os efeitos colaterais são idênticos, incluindo a criação do canal de notas pessoais descrita lá.

Corpo JSON

O corpo é o mesmo de Pré-carregar mensagens de canais privados.

Resposta

Status	Corpo	Condição
200	objeto de mensagens pré-carregadas	Os canais solicitados foram resolvidos

Limite de taxa

40 requisições por 10 segundos para cada usuário autenticado, no bucket user:preload_messages. Os caminhos compartilham a mesma cota.

Fixar canal privado

PUT/v1/users/@me/channels/{channel_id}/pinBot

Adiciona uma mensagem direta ou DM de grupo à ordem de fixados do chamador. Retorna 204 com um corpo vazio. Emite um evento Gateway User Pinned DMs Update.

O Decoding Chat resolve o canal com a autorização de canal comum do chamador primeiro. Um canal privado do qual o chamador não é um destinatário retorna 404 UNKNOWN_CHANNEL, e um canal que não existe retorna a mesma coisa. O canal então tem que ser uma mensagem direta ou uma DM de grupo, de modo que o canal de notas pessoais do chamador e um canal de guilda visível são rejeitados com 400 CHANNEL_MUST_BE_DM_OR_GROUP_DM, um código de campo em channel_id em INVALID_FORM_BODY.

Um canal de guilda que o chamador não pode ver falha na resolução primeiro e retorna 403 MISSING_PERMISSIONS. O Decoding Chat retorna 404 UNKNOWN_GUILD para uma linha de canal que sobreviveu à sua guilda. Onde o registro da guilda ainda existe e o estado de adesão do chamador não pode ser resolvido, a solicitação retorna 403 ACCESS_DENIED.

O Decoding Chat anexa um canal recém-fixado após todo canal já fixado. Um canal posteriormente fechado, abandonado ou excluído permanece no conjunto de fixados, e apenas Desafixar canal privado ou a exclusão da conta do chamador remove uma entrada.

Desafixar exige que o canal resolva

Desafixar resolve o canal primeiro, portanto, uma entrada para um canal excluído, ou para uma DM de grupo da qual o chamador não é mais um destinatário, permanece no conjunto de fixados.

A fixação é idempotente e o Dispatch é incondicional

Fixar um canal já fixado deixa a ordem intacta, mas a operação ainda retorna 204 e emite User Pinned DMs Update com a ordem inalterada.

Parâmetros de caminho

Campo	Tipo	Descrição
channel_id	snowflake	O ID da mensagem direta ou DM de grupo

Resposta

Status	Corpo	Condição
204	vazio	O canal está presente no conjunto de fixados
400	resposta de erro	O canal não é nem uma mensagem direta nem uma DM de grupo e a solicitação retorna CHANNEL_MUST_BE_DM_OR_GROUP_DM
403	resposta de erro	Um canal de guilda não é visível e a solicitação retorna MISSING_PERMISSIONS, ou a guilda existe enquanto a adesão não pôde ser resolvida e a solicitação retorna ACCESS_DENIED
404	resposta de erro	O canal não existe ou o chamador não é um destinatário, cada um retornando UNKNOWN_CHANNEL, ou um canal de guilda sobreviveu à sua guilda e a solicitação retorna UNKNOWN_GUILD

Efeitos colaterais

O canal é anexado à ordem de fixados do chamador, e o User Pinned DMs Update atinge apenas o chamador com a ordem resultante completa como um array de strings de ID de canal. O canal em si não é modificado, e nenhum outro participante pode observar a ordem de fixados do chamador.

Limite de taxa

40 requisições por 10 segundos para cada usuário autenticado, no bucket user:channels, compartilhado com Listar canais privados, Criar canal privado e Desafixar canal privado.

Desafixar canal privado

DELETE/v1/users/@me/channels/{channel_id}/pinBot

Remove uma mensagem direta ou DM de grupo da ordem de fixados do chamador. Retorna 204 com um corpo vazio. Emite um evento Gateway User Pinned DMs Update.

O Decoding Chat resolve e verifica o tipo do canal exatamente como em Fixar canal privado, de modo que um canal que não resolve mais não pode ser desafixado por esta rota. Desafixar preserva a ordem relativa de cada canal que permanece, e uma fixação posterior é anexada ao final. Desafixar um canal que não está fixado ainda retorna 204 e emite o mesmo Dispatch.

Parâmetros de caminho

Campo	Tipo	Descrição
channel_id	snowflake	O ID da mensagem direta ou DM de grupo

Resposta

Status	Corpo	Condição
204	vazio	O canal está ausente do conjunto de fixados
400	resposta de erro	O canal não é nem uma mensagem direta nem uma DM de grupo e a solicitação retorna CHANNEL_MUST_BE_DM_OR_GROUP_DM
403	resposta de erro	Um canal de guilda não é visível e a solicitação retorna MISSING_PERMISSIONS, ou a guilda existe enquanto a adesão não pôde ser resolvida e a solicitação retorna ACCESS_DENIED
404	resposta de erro	O canal não existe ou o chamador não é um destinatário, cada um retornando UNKNOWN_CHANNEL, ou um canal de guilda sobreviveu à sua guilda e a solicitação retorna UNKNOWN_GUILD

Efeitos colaterais

O canal é removido da ordem de fixados do chamador, e o User Pinned DMs Update atinge apenas o chamador com a ordem resultante completa como um array de strings de ID de canal. O canal em si não é fechado ou excluído, e seus destinatários não recebem nenhum Dispatch.

Limite de taxa

40 requisições por 10 segundos para cada usuário autenticado, no bucket user:channels, compartilhado com Listar canais privados, Criar canal privado e Fixar canal privado.