Read states

A read state records how far the current account has read in one channel. It holds the highest message read through, the mention count, and the last acknowledged pin timestamp. The Messages resource defines single-channel acknowledgement, read state deletion, and pin acknowledgement.

Both routes on this page are user-only. Fluxer rejects a bot or OAuth2 credential with 403 ACCESS_DENIED.

Read state object

An account holds at most one read state per channel, keyed by the account and the channel.

Structure

Field	Type	Description
id	snowflake	The ID of the channel the read state belongs to
mention_count1	integer	The number of mentions stored for the channel (0-2,147,483,647)
last_message_id	?snowflake	The highest message ID the account has read through, or null when the entry stores no watermark
last_pin_timestamp2	?ISO8601 timestamp	The time of the last acknowledged pin, or null when pins have never been acknowledged
version?3	string	The read state version as a canonical decimal unsigned 64-bit string

¹ The value the last acknowledgement stored, incremented by the server as new mentions arrive. It is never recomputed from message history

² Neither operation on this page writes it, so an acknowledged pin timestamp survives every message acknowledgement

³ Present on every entry the API returns. The value is always 0

An entry is created by an acknowledgement, by Acknowledge pins, and by the server when a mention arrives in a channel the account has no entry for. A pin acknowledgement writes only last_pin_timestamp, and the entry it creates reports last_message_id as null. An entry the server creates for a mention starts from the channel’s own baseline watermark, which is the snowflake of the channel ID itself, so every message already in the channel stays unread.

Clear channel read state deletes the whole entry, so it drops the watermark and the mention count along with the pin timestamp.

The aggregate is delivered through the Gateway

There is no HTTP read for the read state aggregate. The complete entry array arrives once as read_states in the main Gateway Ready payload.

Only an acknowledgement produces a later Dispatch. A message acknowledgement emits Message ACK, and a pin acknowledgement emits Channel Pins ACK. A server-side mention increment and Clear channel read state both change the stored entry and emit nothing, so the Dispatch stream is not a complete change feed. A client that needs the authoritative aggregate reconciles from a new Ready, or from the entries Acknowledge read states returns.

Example

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

Read state acknowledgement object

One entry in the body of Acknowledge read states. It names the channel whose entry changes, the message the account has read through, and the mention count that survives the read.

Structure

Field	Type	Description
channel_id1	snowflake	The ID of the channel whose read watermark changes
message_id2	snowflake	The ID of the message watermark to acknowledge
mention_count?3	integer	The number of mentions to store for the channel (0-2,147,483,647, default 0)
manual?4	boolean	Whether the stored watermark becomes exactly message_id

¹ Fluxer never resolves the channel. It stores the value as the read state key with no check that the channel exists or that the account can see it

² Fluxer does not resolve the message either. An entry equal to the stored watermark still produces a write, so it resets the stored mention count

³ Fluxer stores the submitted value verbatim, so an acknowledgement leaving mentions above the watermark must send how many remain

⁴ With manual false an entry strictly below the stored watermark is discarded whole

A manual acknowledgement can rewind the watermark

A lower message_id marks later messages unread again. Fluxer replaces the stored mention count at the same time, so a rewinding acknowledgement that omits mention_count clears it.

Example

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

Bulk read state acknowledgement object

One entry in the body of Mark channels as read. It names the channel and the message to read through.

Structure

Field	Type	Description
channel_id1	snowflake	The ID of the channel whose read watermark changes
message_id1	snowflake	The ID of the message watermark to acknowledge

¹ Neither identifier is resolved, so an entry may name a channel or a message that does not exist

Acknowledge read states

POST/v1/read-states/ack

Applies 1 through 100 read state acknowledgement objects to the current account’s aggregate and returns the resulting read state entries. User-only. Emits one Message ACK Gateway event to the caller’s own sessions for each submitted entry.

The route resolves no channel and evaluates no permission. The write mutates only the caller’s own read states.

JSON body

Field	Type	Description
read_states1	array[read state acknowledgement object]	The acknowledgements to apply (1-100)

¹ A list of fewer than 1 or more than 100 entries fails with 400 INVALID_FORM_BODY

Response body

Field	Type	Description
read_states1	array[read state object]	The authoritative entries after the write

¹ One entry for each submitted acknowledgement, in the submitted order. An entry whose watermark did not move reports the values already stored

A plain list takes the batched path

When no entry sets manual and no entry has a mention_count above 0, Fluxer applies the whole list through the batched path Mark channels as read uses.

A list with one manual entry or one positive mention count takes the entry-by-entry path in submitted order, and a later entry naming the same channel is evaluated against the earlier entry’s result.

Response

Status	Body	Condition
200	response body	Acknowledgements were processed and the resulting entries returned
403	error response	Caller is a bot or presents a bearer credential and the request returns ACCESS_DENIED, or the account has an outstanding required action and the request returns ACCOUNT_SUSPICIOUS_ACTIVITY

Side effects

Each entry updates its channel watermark according to the entry’s manual value and stores the submitted mention count. The write invalidates the account’s unread badge total.

One Message ACK goes to the caller’s own sessions for every submitted entry, including one that leaves the watermark and mention count unchanged. The Dispatch has the resulting message_id, mention_count, and version, so a non-manual entry below the stored watermark reports the higher stored value. The entry-by-entry path also has the submitted manual value, and the batched path has no manual at all.

Fluxer logs a failed Dispatch or a failed unread badge invalidation on either path and does not fail the request. A client that misses a Dispatch reconciles from a later read.

Every entry also clears delivered notifications for its channel through the submitted message_id, so a discarded or rewound entry clears a different range than the entry stores.

Rate limit

20 requests per 10 seconds for each authenticated user, on the read_state:ack_bulk bucket, shared with Mark channels as read.

Mark channels as read

POST/v1/read-states/ack-bulk

Applies 1 through 100 bulk read state acknowledgement objects and returns 204 with an empty body. User-only. Emits one Message ACK Gateway event to the caller’s own sessions for each submitted entry.

Every entry advances its channel watermark monotonically and sets the channel’s stored mention count to 0. An entry whose message_id is strictly below the stored watermark is skipped and leaves the stored entry untouched. Like Acknowledge read states, the operation resolves no channel and evaluates no permission.

JSON body

Field	Type	Description
read_states1	array[bulk read state acknowledgement object]	The channel and message pairs to acknowledge (1-100)

¹ Two entries naming the same channel are both evaluated against the value stored before the request

Response

Status	Body	Condition
204	empty	Acknowledgements were processed
403	error response	Caller is a bot or presents a bearer credential and the request returns ACCESS_DENIED, or the account has an outstanding required action and the request returns ACCOUNT_SUSPICIOUS_ACTIVITY

Side effects

An entry equal to the stored watermark still produces a write, and two entries naming the same channel produce two writes. The unread badge total is invalidated once for the whole request.

One Message ACK goes to the caller’s own sessions for every submitted entry, including a skipped one. Every entry clears delivered notifications for its channel through the submitted message_id. The Dispatch has no manual, and a skipped entry reports the stored watermark and mention count.

Fluxer logs a failed Dispatch or a failed unread badge invalidation and does not fail the request, so a client tolerates a missing Dispatch for an entry the write applied.

A failed request can leave some entries written

A request that fails partway leaves the entries already written in place. A retry is safe, because a repeated monotonic acknowledgement is idempotent.

Rate limit

20 requests per 10 seconds for each authenticated user, on the read_state:ack_bulk bucket, shared with Acknowledge read states.