Estados de leitura

Um estado de leitura registra até onde a conta atual leu em um canal. Ele armazena o ID da mensagem mais alta lida, a contagem de menções e o timestamp da última fixação confirmada. O recurso de Mensagens define a confirmação por canal único, a exclusão de estado de leitura e a confirmação de fixações.

Ambas as rotas desta página são exclusivas para usuários. O Decoding Chat rejeita uma credencial de bot ou OAuth2 com 403 ACCESS_DENIED.

Objeto de estado de leitura

Uma conta mantém no máximo um estado de leitura por canal, com chave formada pela conta e o canal.

Estrutura

Campo	Tipo	Descrição
id	snowflake	O ID do canal ao qual o estado de leitura pertence
mention_count1	integer	O número de menções armazenadas para o canal (0–2.147.483.647)
last_message_id	?snowflake	O ID da mensagem mais alta que a conta leu, ou null quando a entrada não armazena marca d’água
last_pin_timestamp2	?ISO8601 timestamp	O horário da última fixação confirmada, ou null quando fixações nunca foram confirmadas
version?3	string	A versão do estado de leitura como string decimal canônica de 64 bits sem sinal

¹ O valor armazenado pela última confirmação, incrementado pelo servidor à medida que novas menções chegam, e nunca recalculado a partir do histórico de mensagens

² Nenhuma das operações desta página o escreve, portanto um timestamp de fixação confirmada sobrevive a toda confirmação de mensagem

³ Presente em cada entrada que a API retorna. O valor é sempre 0

Uma confirmação cria uma entrada. O mesmo faz Confirmar fixações, e também o servidor quando uma menção chega em um canal para o qual a conta não tem entrada. Uma confirmação de fixação escreve apenas last_pin_timestamp, e a entrada criada reporta last_message_id como null. A entrada criada pelo servidor para uma menção parte da marca d’água base do canal — o snowflake do próprio ID do canal —, portanto toda mensagem já existente no canal permanece não lida.

Limpar estado de leitura do canal exclui toda a entrada, removendo a marca d’água, a contagem de menções e o timestamp de fixação.

O agregado é entregue pelo Gateway

Não há leitura HTTP do agregado de estados de leitura. O array completo de entradas chega uma vez como read_states no payload principal Ready do Gateway.

Apenas uma confirmação produz um Dispatch posterior. Uma confirmação de mensagem emite Message ACK, e uma confirmação de fixação emite Channel Pins ACK. Tanto um incremento de menção do lado do servidor quanto Limpar estado de leitura do canal alteram a entrada armazenada sem emitir nada, portanto o fluxo de Dispatch não é um feed completo de alterações. Um cliente que precisa do agregado autoritativo reconcilia a partir de um novo Ready, ou das entradas retornadas por Confirmar estados de leitura.

Exemplo

{
  "id": "1501314428688998182",
  "mention_count": 3,
  "last_message_id": "1501320000000000000",
  "last_pin_timestamp": null,
  "version": "0"
}

Objeto de confirmação de estado de leitura

Uma entrada no corpo de Confirmar estados de leitura. Nomeia o canal cuja entrada muda, a mensagem até a qual a conta leu e a contagem de menções a armazenar para o canal.

Estrutura

Campo	Tipo	Descrição
channel_id1	snowflake	O ID do canal cuja marca d’água de leitura muda
message_id2	snowflake	O ID da mensagem a ser confirmada como marca d’água
mention_count?3	integer	O número de menções a armazenar para o canal (0–2.147.483.647, padrão 0)
manual?4	boolean	Se a marca d’água armazenada passa a ser exatamente message_id

¹ O Decoding Chat nunca resolve o canal. Ele armazena o valor como chave do estado de leitura sem verificar se o canal existe ou se a conta pode vê-lo

² O Decoding Chat também não resolve a mensagem. Uma entrada igual à marca d’água armazenada ainda produz uma escrita, redefinindo a contagem de menções armazenada

³ O Decoding Chat armazena o valor enviado literalmente, portanto um cliente que deixa menções não lidas após message_id deve enviar o número dessas menções

⁴ Com manual false, uma entrada estritamente abaixo da marca d’água armazenada é descartada inteira

Uma confirmação manual pode retroceder a marca d’água

Um message_id menor marca mensagens posteriores como não lidas novamente. O Decoding Chat substitui a contagem de menções armazenada ao mesmo tempo, portanto uma confirmação retroativa que omite mention_count a zera.

Exemplo

{
  "channel_id": "1501314428688998182",
  "message_id": "1501320000000000000",
  "mention_count": 0
}

Objeto de confirmação em lote de estado de leitura

Uma entrada no corpo de Marcar canais como lidos. Nomeia o canal e a mensagem a ser marcada como lida.

Estrutura

Campo	Tipo	Descrição
channel_id1	snowflake	O ID do canal cuja marca d’água de leitura muda
message_id1	snowflake	O ID da mensagem a ser confirmada como marca d’água

¹ Nenhum dos identificadores é resolvido, portanto uma entrada pode nomear um canal ou mensagem que não existe

Confirmar estados de leitura

POST/v1/read-states/ack

Aplica 1 a 100 objetos de confirmação de estado de leitura ao agregado da conta atual e retorna as entradas de estado de leitura resultantes. Exclusivo para usuários. Emite um evento Gateway Message ACK para as próprias sessões do chamador para cada entrada enviada.

A rota não resolve nenhum canal e não avalia nenhuma permissão. A escrita altera apenas os estados de leitura do próprio chamador.

Corpo JSON

Campo	Tipo	Descrição
read_states1	array[objeto de confirmação de estado de leitura]	As confirmações a aplicar (1–100)

¹ Uma lista com menos de 1 ou mais de 100 entradas falha com 400 INVALID_FORM_BODY

Corpo da resposta

Campo	Tipo	Descrição
read_states1	array[objeto de estado de leitura]	As entradas autoritativas após a escrita

¹ Uma entrada para cada confirmação enviada, na ordem enviada. Uma entrada cuja marca d’água não avançou reporta os valores já armazenados

Quando qualquer entrada é manual ou tem contagem de menções positiva, entradas para o mesmo canal são aplicadas na ordem enviada. Caso contrário, cada entrada é avaliada contra o estado anterior à requisição.

Resposta

Status	Corpo	Condição
200	corpo da resposta	Confirmações foram processadas e as entradas resultantes retornadas
403	resposta de erro	O chamador é um bot ou apresenta credencial bearer e a requisição retorna ACCESS_DENIED, ou a conta tem uma ação pendente obrigatória e retorna ACCOUNT_SUSPICIOUS_ACTIVITY

Efeitos colaterais

Com manual true, uma entrada define a marca d’água do canal como message_id. Com manual false, o Decoding Chat descarta uma entrada estritamente abaixo da marca d’água armazenada e deixa a entrada armazenada inalterada. Toda entrada não descartada define a marca d’água como message_id e armazena a contagem de menções enviada.

Um Message ACK vai para as sessões do chamador para cada entrada enviada, incluindo uma inalterada. Ele reporta o message_id, mention_count e version resultantes. Também inclui o valor manual enviado quando qualquer entrada é manual ou tem contagem de menções positiva.

Quando o Decoding Chat falha ao enviar um Message ACK, a requisição ainda tem sucesso e nenhum Dispatch chega para aquela entrada. Um cliente reconcilia a partir das entradas retornadas por esta rota ou de um novo Ready.

Toda entrada também limpa notificações push entregues para seu canal até o message_id enviado. O Decoding Chat usa o valor enviado mesmo quando descarta a entrada e mantém uma marca d’água armazenada maior.

Rate limit

20 requisições por 10 segundos para cada usuário autenticado, no bucket read_state:ack_bulk, compartilhado com Marcar canais como lidos.

Marcar canais como lidos

POST/v1/read-states/ack-bulk

Aplica 1 a 100 objetos de confirmação em lote de estado de leitura e retorna 204 com corpo vazio. Exclusivo para usuários. Emite um evento Gateway Message ACK para as próprias sessões do chamador para cada entrada enviada.

Toda entrada avança sua marca d’água de canal monotonicamente e define a contagem de menções armazenada do canal como 0. Uma entrada cujo message_id é estritamente abaixo da marca d’água armazenada é ignorada e deixa a entrada armazenada inalterada. Como Confirmar estados de leitura, a operação não resolve nenhum canal e não avalia nenhuma permissão.

Corpo JSON

Campo	Tipo	Descrição
read_states1	array[objeto de confirmação em lote de estado de leitura]	Os pares de canal e mensagem a confirmar (1–100)

¹ Duas entradas nomeando o mesmo canal são ambas avaliadas contra o valor armazenado antes da requisição

Resposta

Status	Corpo	Condição
204	vazio	Confirmações foram processadas
403	resposta de erro	O chamador é um bot ou apresenta credencial bearer e a requisição retorna ACCESS_DENIED, ou a conta tem uma ação pendente obrigatória e retorna ACCOUNT_SUSPICIOUS_ACTIVITY

Efeitos colaterais

Uma entrada igual à marca d’água atual redefine a contagem de menções para 0.

Um Message ACK vai para as próprias sessões do chamador para cada entrada enviada, incluindo uma ignorada. Toda entrada limpa notificações entregues para seu canal até o message_id enviado. O Dispatch não tem manual, e uma entrada ignorada reporta a marca d’água e contagem de menções armazenadas.

Uma confirmação bem-sucedida pode não ter Dispatch correspondente.

Uma requisição com falha pode deixar algumas entradas escritas

Uma requisição que falha no meio deixa as entradas já escritas em vigor. Uma nova tentativa é segura, pois uma confirmação monotônica repetida é idempotente.

Rate limit

20 requisições por 10 segundos para cada usuário autenticado, no bucket read_state:ack_bulk, compartilhado com Confirmar estados de leitura.