Relacionamentos

Um relacionamento descreve uma amizade, bloqueio ou solicitação de amizade pendente da perspectiva do chamador. Notas privadas pertencem a Notas de usuário.

As rotas aqui são apenas para usuários. Um bot ou credencial bearer OAuth2 recebe 403 ACCESS_DENIED, e uma conta com uma ação obrigatória pendente recebe 403 ACCOUNT_SUSPICIOUS_ACTIVITY.

Registros de relacionamento são direcionais

Uma amizade é um registro FRIEND em ambas as contas. Uma solicitação pendente é OUTGOING_REQUEST no remetente e INCOMING_REQUEST no destinatário. Um bloqueio existe apenas na conta que o criou, então o bloqueio não adiciona nenhum registro à conta bloqueada e não envia a ela nenhum Relationship Add.

Uma conta excluída tem o sinalizador de exclusão sem registro de data e hora de exclusão pendente e não é um alvo válido para solicitação de amizade. Uma conta dentro de uma janela de exclusão agendada tem um registro de data e hora, portanto, permanece um alvo válido.

Objeto de relacionamento

Um registro de relacionamento pertence a uma conta e nomeia uma outra conta. Cada campo descreve o lado da conta proprietária. O chamador lê seu próprio registro em cada operação, exceto a aceitação automática de bot amigável de Enviar solicitação de amizade por ID de usuário, que retorna o registro do bot.

Estrutura

Campo	Tipo	Descrição
id1	snowflake	O ID da conta relacionada
type	inteiro	O tipo de relacionamento
user	objeto usuário parcial	A conta relacionada
since?2	timestamp ISO8601	O momento em que o tipo atual do registro foi estabelecido
nickname3	?string	O apelido privado do chamador para a conta relacionada, ou null quando nenhum está definido
share_voice_activity4	booleano	Se o chamador compartilha a atividade de voz com a conta relacionada
friend_shares_voice_activity5	booleano	Se a conta relacionada compartilha a atividade de voz com o chamador

¹ Um relacionamento não tem identificador próprio, portanto, este é sempre o ID da conta relacionada

² Omitido quando o registro armazenado não possui registro de data e hora. Uma gravação de apelido e uma reescrita de compartilhamento o preservam, portanto, ele não rastreia a última gravação

³ Apenas um registro FRIEND tem um, e Modificar apelido de relacionamento é seu único gravador. Uma alteração de tipo reescreve o registro, de modo que um apelido não sobrevive a uma

⁴ Um registro FRIEND é gravado com o padrão da conta proprietária quando a amizade é criada. Todo registro não-FRIEND é gravado como true

⁵ Apenas Listar relacionamentos resolve o registro recíproco. Todas as outras operações relatam true, e o mesmo ocorre com Listar relacionamentos para um registro sem recíproco de seu tipo

Exemplo

{
  "id": "1501314428688998182",
  "type": 1,
  "user": {"id": "1501314428688998182", "username": "aria", "discriminator": "0042"},
  "since": "2026-01-14T09:31:00.000Z",
  "nickname": "climbing partner",
  "share_voice_activity": true,
  "friend_shares_voice_activity": false
}

Tipos de relacionamento

Valor	Nome	Descrição
1	FRIEND	As duas contas são amigas
2	BLOCKED	O chamador bloqueou a conta relacionada
3	INCOMING_REQUEST	A conta relacionada enviou uma solicitação de amizade ao chamador
4	OUTGOING_REQUEST	O chamador enviou uma solicitação de amizade à conta relacionada

Objeto de resultado de ignorar em massa

Um resultado de ignorar em massa relata quantas solicitações de amizade recebidas uma chamada removeu.

Estrutura

Campo	Tipo	Descrição
ignored_count	inteiro	O número de solicitações de amizade recebidas que foram removidas

Filtros de ignorar em massa

Valor	Nome	Descrição
all	Todos	Corresponde a todas as solicitações de amizade recebidas
new_accounts1	Novas contas	Corresponde a uma solicitação de amizade recebida cuja conta do remetente é mais recente que max_account_age_seconds

¹ A comparação de idade se aplica apenas quando max_account_age_seconds é fornecido, portanto, esse filtro corresponde a todas as solicitações recebidas quando esse membro está ausente

Limite de relacionamento

O limite max_relationships controla o número combinado de registros de amizade, bloqueio e solicitações pendentes que uma conta possui. O Decoding Chat resolve isso a partir dos traços e estado premium da conta, para que o valor possa ser maior para uma conta premium. O fallback é 1000 quando a implantação não resolve nenhuma regra. A entrada de registro está listada em chaves de limite.

O Decoding Chat recusa a gravação assim que a contagem de registros armazenados atinge o valor resolvido. Ele verifica o chamador e o alvo de forma independente, e uma solicitação falha quando qualquer um deles atinge esse valor.

Uma recusa retorna 400 MAX_FRIENDS com o valor aplicado em um membro de nível superior max_relationships. O Decoding Chat ignora o limite para uma conta de bot de ambos os lados, para um bloqueio e sob aceitação forçada por equipe.

Listar relacionamentos

GET/v1/users/@me/relationships

Retorna cada objeto de relacionamento que o chamador possui, cobrindo amizades, bloqueios e solicitações pendentes em ambas as direções.

A operação não é paginada e todo o conjunto volta em uma única resposta. A ordem não é confiável.

Resposta

Status	Corpo	Condição
200	array[objeto de relacionamento]	Os relacionamentos foram retornados

Limite de taxa

40 requisições por 10 segundos para cada usuário autenticado, no bucket user:relationships:list.

Enviar solicitação de amizade por tag

POST/v1/users/@me/relationships

Envia uma solicitação de amizade para a conta identificada pelo nome de usuário e discriminador. Retorna um objeto de relacionamento em caso de sucesso.

Limitações

• Uma tag não resolvida retorna 400 NO_USERS_WITH_FLUXERTAG_EXIST.
• Uma conta excluída resolvida retorna 400 FRIEND_REQUEST_BLOCKED.
• Uma amizade existente retorna 400 ALREADY_FRIENDS.

O Decoding Chat resolve a tag para exatamente uma conta antes de qualquer regra de relacionamento ser executada. Todas as regras de admissão restantes são as descritas em Enviar solicitação de amizade por ID de usuário.

Corpo JSON

Campo	Tipo	Descrição
username1	string	O nome de usuário da conta de destino
discriminator2	string | inteiro	O discriminador da conta de destino

¹ Cortado antes da validação, depois de 1 a 32 caracteres de letras ASCII, dígitos e sublinhados. Não pode ser everyone ou here, ou conter fluxer ou system message, em qualquer forma de capitalização

² Um número inteiro e uma string decimal de 1 a 4 dígitos são aceitos, e 0007 e 7 resolvem a mesma conta

Resposta

Status	Corpo	Condição
200	objeto de relacionamento	Uma solicitação pendente, um relacionamento existente ou uma amizade aceita foi retornada
400	resposta de erro	A tag não foi resolvida, o chamador ou o alvo é inelegível, a política de alvo ou de bloqueio rejeita a solicitação, a política de implantação desabilita a operação ou o limite de relacionamento é atingido
403	resposta de erro	O endereço de email do chamador não foi verificado e a solicitação retorna FRIEND_REQUEST_EMAIL_VERIFICATION_REQUIRED
404	resposta de erro	O chamador ou o alvo resolvido não existe mais, ou a solicitação pendente sendo aceita foi retirada

Efeitos colaterais

Os efeitos colaterais são os de Enviar solicitação de amizade por ID de usuário. Nenhuma das rotas abre um canal de mensagens diretas.

Limite de taxa

10 requisições por minuto para cada usuário autenticado, no bucket user:friend_request:send, compartilhado com Enviar solicitação de amizade por ID de usuário.

Enviar solicitação de amizade por ID de usuário

POST/v1/users/@me/relationships/{user_id}

Envia uma solicitação de amizade para a conta selecionada. Retorna um objeto de relacionamento em caso de sucesso.

A admissão é ordenada. A política de mensagem direta da implantação é executada primeiro, de modo que um chamador comum recebe 400 DIRECT_MESSAGES_DISABLED enquanto essa política desabilita mensagens diretas. Um chamador com a flag STAFF ignora essa primeira avaliação, independentemente de solicitar aceitação forçada ou não. Quando o destino já enviou uma solicitação, o envio de um chamador da equipe se transforma em uma aceitação e ainda recebe 400 DIRECT_MESSAGES_DISABLED. Um chamador não resolvido retorna 404 UNKNOWN_USER.

O próprio ID do chamador retorna 400 CANNOT_SEND_FRIEND_REQUEST_TO_SELF. Um alvo não resolvido retorna 404 UNKNOWN_USER. Um alvo excluído retorna 400 FRIEND_REQUEST_BLOCKED.

O Decoding Chat verifica o estado do relacionamento atual em seguida. Uma solicitação pendente do destino é aceita. Uma amizade existente ou solicitação enviada é retornada inalterada. As regras que se seguem se aplicam apenas a uma solicitação genuinamente nova, portanto, nunca recusam um amigo existente.

As regras restantes rejeitam um chamador não reivindicado com 400 UNCLAIMED_ACCOUNT_CANNOT_SEND_FRIEND_REQUESTS e um email não verificado com 403 FRIEND_REQUEST_EMAIL_VERIFICATION_REQUIRED. Um alvo bot é rejeitado com 400 FRIEND_REQUEST_BLOCKED a menos que tenha FRIENDLY_BOT. Um alvo com a flag de revisor da loja de aplicativos internos é rejeitado com o mesmo código.

Um alvo que o chamador bloqueou retorna 400 CANNOT_SEND_FRIEND_REQUEST_TO_BLOCKED_USER. Um alvo que bloqueou o chamador retorna 400 FRIEND_REQUEST_BLOCKED. O Decoding Chat lê as flags de origem de amigo do alvo a seguir¹, e um alvo aceitando solicitações apenas de amigos em comum ou membros de guilda em comum rejeita um chamador não relacionado com 400 FRIEND_REQUEST_BLOCKED. O limite de relacionamento se aplica por último, de forma independente para ambas as contas.

¹ A avaliação da fonte do amigo é ignorada quando o alvo não tem configurações armazenadas, o que admite a solicitação como se o alvo permitisse solicitações de qualquer pessoa

Um chamador sinalizado recebe um sucesso indistinguível

Um chamador com a flag SPAMMER de usuário público, ou aquele cujo envio aciona a política de spam de contato direto da implantação, recebe uma solicitação unilateral. O Decoding Chat grava apenas o registro OUTGOING_REQUEST do chamador. Relationship Add chega apenas ao chamador. A resposta é um objeto OUTGOING_REQUEST comum.

O caminho de solicitação unilateral também ignora as regras que o seguem: o bloqueio do chamador pelo alvo, as flags de origem de amigo do alvo, a regra do revisor da app store, o limite de relacionamento e a aceitação automática de bot amigável. O próprio bloqueio do chamador ao alvo ainda é imposto e ainda retorna 400 CANNOT_SEND_FRIEND_REQUEST_TO_BLOCKED_USER. Quando a política de spam de contato direto suprime um envio e sua ação é flag_spammer, o Decoding Chat também define a flag SPAMMER no chamador, o que torna todos os envios subsequentes unilaterais.

As entradas de supressão entram em pontos diferentes

O Decoding Chat verifica a flag SPAMMER antes de procurar uma solicitação pendente do alvo. Um chamador que já possui a flag recebe uma solicitação unilateral mesmo quando o alvo possui uma solicitação pendente, de modo que pode conter um registro INCOMING_REQUEST e OUTGOING_REQUEST para uma conta. O Decoding Chat aplica a política de spam de contato direto após essa pesquisa, portanto, um chamador sem a flag aceita uma solicitação pendente do alvo normalmente.

Parâmetros de caminho

Campo	Tipo	Descrição
user_id	snowflake	O ID da conta de destino

Corpo JSON

O corpo pode ser omitido, caso em que é tratado como um objeto vazio.

Campo	Tipo	Descrição
staff_force_accept?1	booleano	Se a amizade é criada imediatamente sem uma solicitação pendente

¹ Honrado apenas quando o chamador possui a flag STAFF, e um chamador sem ele é tratado como se o membro estivesse ausente. O Decoding Chat lê a flag armazenada, portanto, o status da equipe oculta ainda se qualifica

Resposta

Status	Corpo	Condição
200	objeto de relacionamento	Uma solicitação pendente, um relacionamento existente ou uma amizade aceita foi retornada
400	resposta de erro	O chamador ou o alvo é inelegível, a política de alvo ou de bloqueio rejeita a solicitação, a política de implantação desabilita a operação ou o limite de relacionamento é atingido
403	resposta de erro	O endereço de email do chamador não foi verificado e a solicitação retorna FRIEND_REQUEST_EMAIL_VERIFICATION_REQUIRED
404	resposta de erro	O chamador, a conta de destino ou a solicitação pendente sendo aceita não existe

Efeitos colaterais

Uma nova solicitação grava registros correspondentes OUTGOING_REQUEST e INCOMING_REQUEST e emite Relationship Add para ambas as contas. Ambos os registros são gravados com share_voice_activity definido como true.

Quando o alvo já enviou uma solicitação ao chamador, a operação aceita essa solicitação. A aceitação substitui ambos os registros pendentes por registros FRIEND e emite Relationship Update para ambas as contas, e cada registro FRIEND tem share_voice_activity definido para o default_share_voice_activity de sua conta proprietária. Nenhum caminho de aceitação nesta rota abre um canal de mensagem direta, ao contrário de Aceitar solicitação ou bloquear usuário.

Um alvo de bot que tem FRIENDLY_BOT sem FRIENDLY_BOT_MANUAL_APPROVAL aceita na mesma chamada, então o chamador observa Relationship Add seguido de Relationship Update. Ambas as flags são lidas apenas em uma conta de bot. O corpo da resposta dessa chamada é o próprio registro do bot, e seu id e user nomeiam o chamador e seu share_voice_activity é o padrão do bot. O Dispatch que o chamador recebe contém o registro do chamador.

A aceitação forçada pela equipe substitui todos os registros existentes entre as duas contas, em qualquer direção, por uma amizade e emite Relationship Add para ambas. Um registro substituído emite no máximo um Relationship Remove para cada conta primeiro. Quando as duas contas já têm uma amizade mútua e nada mais, o registro existente retorna inalterado. A aceitação forçada ainda impõe a regra de si mesmo, ambas as regras de conta não resolvida, a regra de conta excluída em ambas as partes, a regra de conta não reivindicada e a regra de verificação de email. Ela não impõe nenhuma regra de relacionamento, portanto, substitui um bloqueio em qualquer direção, as flags de origem de amigo do alvo, a regra de alvo de bot e o limite de relacionamento.

Limite de taxa

10 requisições por minuto para cada usuário autenticado, no bucket user:friend_request:send, compartilhado com Enviar solicitação de amizade por tag.

Aceitar solicitação ou bloquear usuário

PUT/v1/users/@me/relationships/{user_id}

Aceita uma solicitação de amizade recebida pendente ou bloqueia a conta selecionada quando o corpo seleciona BLOCKED. Retorna um objeto de relacionamento em caso de sucesso.

A aceitação avalia a política de mensagem direta da implantação primeiro e retorna 400 DIRECT_MESSAGES_DISABLED enquanto essa política desabilita mensagens diretas, sem isenção para a equipe. Um chamador ou solicitante não resolvido retorna 404 UNKNOWN_USER. Uma conta excluída em qualquer um dos lados retorna 400 FRIEND_REQUEST_BLOCKED. Um chamador não reivindicado retorna 400 UNCLAIMED_ACCOUNT_CANNOT_ACCEPT_FRIEND_REQUESTS. Uma solicitação de entrada pendente ausente retorna 404 UNKNOWN_USER, e o limite de relacionamento então se aplica a ambas as contas. A aceitação não possui requisito de verificação de email.

O bloqueio retorna 404 UNKNOWN_USER para um alvo não resolvido e 400 CANNOT_BLOCK_SYSTEM_USER para a conta de sistema do Decoding Chat. Essas são suas únicas regras de admissão, de modo que o bloqueio é executado independentemente da política de mensagens diretas da implantação, da regra de conta não reivindicada, da regra de verificação de email e do limite de relacionamento. Ele não aplica regra de auto-alvo.

O membro tipo seleciona a operação

Apenas o valor exato BLOCKED seleciona o bloqueio. Todos os outros tipos de relacionamento aceitos, um type omitido e um corpo omitido selecionam a aceitação de uma solicitação recebida pendente. O envio de FRIEND não força uma amizade onde não existe solicitação.

Parâmetros de caminho

Campo	Tipo	Descrição
user_id	snowflake	O ID da conta de destino

Corpo JSON

O corpo pode ser omitido, caso em que é tratado como um objeto vazio e a aceitação é selecionada.

Campo	Tipo	Descrição
type?1	inteiro	O tipo de relacionamento selecionando a operação

¹ Um dos tipos enumerados quando presente. Apenas BLOCKED seleciona o bloqueio, e todos os outros valores aceitos selecionam a aceitação

Resposta

Status	Corpo	Condição
200	objeto de relacionamento	A amizade ou o bloqueio foi retornado
400	resposta de erro	Uma conta é inelegível, o alvo do bloqueio é a conta do sistema, a política de implantação desabilita a aceitação ou o limite de relacionamento é atingido
404	resposta de erro	A conta de destino não existe ou nenhuma solicitação recebida pendente existe

Efeitos colaterais

A aceitação substitui os registros pendentes por registros FRIEND em ambas as contas e emite Relationship Update para cada uma. Em seguida, ela abre o canal de mensagens diretas do par para ambas as contas, criando o canal quando não existe e emite Channel Create para cada conta cujo estado aberto foi alterado. Nenhuma outra operação de relacionamento abre um.

O bloqueio substitui a amizade existente ou a solicitação pendente do chamador por um registro BLOCKED. Remover uma amizade ou uma solicitação enviada também remove o registro recíproco do alvo, e o Relationship Remove atinge o alvo. Remover uma solicitação de entrada afeta apenas o registro do chamador. O Relationship Add então atinge o chamador para o bloqueio. Bloquear um alvo já bloqueado não muda nada. Bloquear nunca fecha ou exclui o canal de mensagens diretas do par.

Limite de taxa

20 requisições por 10 segundos para cada usuário autenticado, no bucket user:friend_request:accept.

Remover relacionamento

DELETE/v1/users/@me/relationships/{user_id}

Remove a amizade atual do chamador, solicitação de amizade pendente em qualquer direção ou bloqueio envolvendo a conta selecionada. Retorna 204 com um corpo vazio em caso de sucesso.

A rota não lê nenhum corpo da solicitação. O registro atual do chamador determina o que é removido. Um chamador sem nenhum registro de qualquer tipo recebe 404 UNKNOWN_USER. A remoção não tem política de implantação, verificação de email, conta não reivindicada ou regra de limite, de modo que um relacionamento permanece removível enquanto todos os caminhos de criação estão fechados.

Parâmetros de caminho

Campo	Tipo	Descrição
user_id	snowflake	O ID da conta relacionada

Resposta

Status	Corpo	Condição
204	vazio	O relacionamento foi removido
404	resposta de erro	Nenhum relacionamento de nenhum tipo existe com o alvo

Efeitos colaterais

A remoção de uma amizade ou de uma solicitação enviada remove os registros de ambas as contas e emite Relationship Remove para cada conta.

Um bloqueio é armazenado em apenas uma conta, portanto, remover um exclui o registro do chamador e emite Relationship Remove apenas para o chamador.

Rejeitar uma solicitação de entrada deixa o registro do remetente

Remover um registro INCOMING_REQUEST exclui apenas o registro do chamador e notifica apenas o chamador. O remetente mantém seu registro OUTGOING_REQUEST e não consegue saber se a solicitação foi rejeitada. Ignorar solicitações pendentes em massa remove ambos os registros em vez disso.

Limite de taxa

30 requisições por 10 segundos para cada usuário autenticado, no bucket user:relationship:delete.

Modificar apelido de relacionamento

PATCH/v1/users/@me/relationships/{user_id}

Define ou limpa o apelido privado do chamador para um amigo. Retorna o objeto de relacionamento atualizado. Emite um evento Gateway Relationship Update.

Apenas um registro FRIEND aceita um apelido, e todos os outros estados de relacionamento retornam 404 UNKNOWN_USER.

O apelido é privado ao chamador

O Decoding Chat grava isso apenas no registro do chamador. O amigo nunca o lê em uma resposta e nunca o recebe em um Dispatch.

Parâmetros de caminho

Campo	Tipo	Descrição
user_id	snowflake	O ID do amigo

Corpo JSON

Campo	Tipo	Descrição
nickname1	?string	O apelido a armazenar, ou null para limpá-lo

¹ O membro é obrigatório, portanto, um corpo vazio é rejeitado. O valor é cortado, destituído dos caracteres form feed e de sobreposição da direita para a esquerda e, em seguida, tem no máximo 256 caracteres

Uma string vazia literal limpa o apelido, o mesmo que null. Um valor que é apenas espaço em branco é normalizado para uma string vazia e é armazenado como uma.

Resposta

Status	Corpo	Condição
200	objeto de relacionamento	O relacionamento atualizado foi retornado
404	resposta de erro	Nenhum registro FRIEND existe com o alvo

Efeitos colaterais

O registro muda apenas para o chamador, e a preferência de compartilhamento mantém seu valor armazenado. Um valor since armazenado é preservado, e um registro que não o possui é carimbado com o tempo atual. Relationship Update atinge o chamador para cada solicitação aceita, incluindo uma que envia o valor já armazenado.

Limite de taxa

30 requisições por 10 segundos para cada usuário autenticado, no bucket user:relationship:update.

Ignorar solicitações pendentes em massa

POST/v1/users/@me/relationships/bulk-ignore

Remove solicitações de amizade recebidas correspondentes. Retorna um objeto de resultado de ignorar em massa em caso de sucesso.

A correspondência se aplica apenas aos registros INCOMING_REQUEST do chamador. O Decoding Chat deriva a idade da conta do remetente a partir do timestamp embutido em seu snowflake e o compara com max_account_age_seconds como um limite superior exclusivo, de forma que um remetente exatamente com essa idade não é correspondido. Uma chamada remove todas as solicitações correspondentes.

Um filtro new_accounts ilimitado remove tudo

A comparação de idade se aplica apenas quando max_account_age_seconds é fornecido. Selecionar new_accounts sem ele remove todas as solicitações de amizade recebidas, exatamente como all faz.

Corpo JSON

O corpo pode ser omitido, caso em que é tratado como um objeto vazio e o filtro all se aplica.

Campo	Tipo	Descrição
filter?	string	O filtro de ignorar em massa a ser aplicado (padrão all)
max_account_age_seconds?1	inteiro	A idade máxima exclusiva da conta do remetente em segundos

¹ Um número inteiro positivo, lido apenas pelo filtro new_accounts

Resposta

Status	Corpo	Condição
200	objeto de resultado de ignorar em massa	As solicitações correspondentes foram removidas

Efeitos colaterais

Cada solicitação correspondente remove o registro INCOMING_REQUEST do chamador e o registro OUTGOING_REQUEST do remetente, e emite Relationship Remove para o chamador e para o remetente. Uma chamada que não corresponde a nada não altera nada.

Uma chamada que falha no meio do caminho pode remover algumas solicitações de amizade recebidas e não retornar contagem nenhuma. Chame Listar relacionamentos novamente para ler o que resta.

Limite de taxa

5 requisições por minuto para cada usuário autenticado, no bucket user:friend_request:bulk_ignore.