Notas de usuário

Uma nota é um texto privado e curto que o chamador armazena sobre outra conta.

Cada rota aqui exige uma sessão de usuário. Uma credencial de bot ou bearer OAuth2 é recusada com 403 ACCESS_DENIED. Uma conta com uma ação obrigatória pendente é recusada com 403 ACCOUNT_SUSPICIOUS_ACTIVITY.

Uma nota é privada para seu autor

A conta de destino nunca recebe a nota em uma resposta HTTP ou no Gateway Dispatch. Uma nota não tem requisito de relacionamento, então o chamador pode manter uma para uma conta que não seja nem de um amigo nem bloqueada.

Objeto user note

Uma única nota que o chamador mantém para uma conta de destino.

Estrutura

Campo	Tipo	Descrição
note1	string	O texto da nota que o chamador armazenou para a conta de destino

¹ Nunca nulo e nunca uma string vazia. Uma nota armazenada tem sempre de 1 a 256 caracteres após a normalização, e uma note omitida, nula ou vazia exclui a nota armazenada

Registro de user notes

Todas as notas que o chamador armazenou. O registro é um map[snowflake, string]. O nome de cada propriedade é o snowflake de uma conta de destino, e seu valor é o texto da nota desse destino.

O Gateway entrega o mesmo mapa que o campo notes do payload READY, de forma que um cliente conectado já possui o registro antes de chamar a operação de listagem.

Estrutura

Campo	Tipo	Descrição
{target_id}1	string	O texto da nota armazenada para a conta nomeada pela propriedade

¹ Um destino sem nota não possui propriedade, portanto, uma conta sem notas recebe um objeto vazio

Exemplo

{
  "1501314428688998182": "conheci no encontro em Berlim",
  "1501314428688998183": "sempre posta os links bons"
}

Listar notas de usuário

GET/v1/users/@me/notes

Retorna o registro de user notes completo do chamador. A operação não é paginada, então toda nota armazenada retorna em uma única resposta.

Uma nota não possui timestamp de criação ou modificação.

Resposta

Status	Corpo	Condição
200	registro de user notes	Notas foram retornadas, possivelmente como um objeto vazio

Limite de taxa

60 requisições a cada 10 segundos para cada usuário autenticado, no bucket user:notes:read, compartilhado com Obter nota de usuário.

Obter nota de usuário

GET/v1/users/@me/notes/{target_id}

Retorna o objeto user note do chamador para uma conta de destino.

Um destino sem nota armazenada retorna 404 UNKNOWN_USER. O mesmo status abrange uma conta que existe sem nota e um ID que não nomeia conta nenhuma.

Parâmetros de caminho

Campo	Tipo	Descrição
target_id1	snowflake	O ID da conta que a nota descreve

¹ O Decoding Chat remove espaços em branco à esquerda e à direita antes de ler o valor. Um zero à esquerda, um sinal, um ponto decimal ou qualquer outro caractere não numérico retorna 400 INVALID_FORM_BODY com o código de validação INVALID_SNOWFLAKE_FORMAT, e um valor acima de 9223372036854775807 retorna SNOWFLAKE_OUT_OF_RANGE

Resposta

Status	Corpo	Condição
200	objeto user note	A nota foi retornada
404	resposta de erro	Nenhuma nota está armazenada para o ID de destino e a requisição retorna UNKNOWN_USER

Limite de taxa

60 requisições a cada 10 segundos para cada usuário autenticado, no bucket user:notes:read, compartilhado com Listar notas de usuário.

Definir nota de usuário

PUT/v1/users/@me/notes/{target_id}

Cria, substitui ou exclui a nota do chamador para uma conta de destino. Retorna 204 com um corpo vazio. Emite um evento de Gateway User Note Update.

O texto fornecido se torna a nota armazenada completa. Um ID de destino que não nomeia conta alguma retorna 404 UNKNOWN_USER, mesmo quando a requisição iria apenas excluir uma nota. O chamador pode armazenar uma nota para qualquer conta existente, incluindo uma conta de bot, sua própria conta e uma conta com a qual não possui relacionamento.

Uma nota omitida, nula ou vazia a exclui

Uma string vazia é lida como null, de forma que os formatos são indistinguíveis. Qualquer valor que seja normalizado para a string vazia, como um composto apenas por espaços em branco, falha na validação com STRING_LENGTH_INVALID. Não há rota separada para exclusão.

Uma note de pelo menos 3 caracteres que corresponda à lista de bloqueio de frases da instância, ou com uma URL correspondente à lista de bloqueio de URLs, é rejeitada com 403 CONTENT_BLOCKED. A verificação da lista de bloqueio ocorre antes das próprias verificações de credencial e de corpo da rota, então um valor bloqueado é recusado com CONTENT_BLOCKED mesmo quando a requisição falharia também em uma dessas verificações.

Parâmetros de caminho

Campo	Tipo	Descrição
target_id1	snowflake	O ID da conta que a nota descreve

¹ O Decoding Chat remove espaços em branco à esquerda e à direita antes de ler o valor. Um zero à esquerda, um sinal, um ponto decimal ou qualquer outro caractere não numérico retorna INVALID_SNOWFLAKE_FORMAT, e um valor acima de 9223372036854775807 retorna SNOWFLAKE_OUT_OF_RANGE

Corpo JSON

O Decoding Chat lê um corpo omitido como um objeto vazio e exclui a nota armazenada.

Campo	Tipo	Descrição
note?1	?string	O texto completo da nota de substituição, ou null para excluir a nota armazenada (1-256 caracteres)

¹ O Decoding Chat apara o valor e o limite se aplica ao resultado, então um valor que aparado se torna vazio retorna STRING_LENGTH_INVALID no caminho note

Resposta

Status	Corpo	Condição
204	vazio	A nota foi definida ou excluída
403	resposta de erro	A nota está bloqueada pela moderação de conteúdo e a requisição retorna CONTENT_BLOCKED
404	resposta de erro	A conta de destino não existe e a requisição retorna UNKNOWN_USER

Efeitos colaterais

Fornecer texto cria ou substitui a nota, e uma requisição que não fornece texto a exclui. O evento User Note Update alcança as sessões do próprio chamador para cada requisição aceita, incluindo uma que forneça o valor atual e uma que exclua uma nota inexistente. Seu payload tem o ID de destino em id e o texto da nota em note. Em uma exclusão, o texto da nota é a string vazia.

Limite de taxa

40 requisições a cada 10 segundos para cada usuário autenticado, no bucket user:notes:write.