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. FiveCord 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 and 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 acknowledgement creates an entry. So does Acknowledge pins, and so does 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. The entry the server creates for a mention starts from the channel’s own baseline watermark, 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. Both a server-side mention increment and Clear channel read state 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 to store for the channel.

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

¹ FiveCord 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

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

³ FiveCord stores the submitted value verbatim, so a client that leaves unread mentions after message_id must send the number of those mentions

⁴ 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. FiveCord 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 changes 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

When any entry is manual or has a positive mention count, entries for the same channel apply in submitted order. Otherwise, each entry is evaluated against the state before the request.

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

With manual true, an entry sets the channel watermark to message_id. With manual false, FiveCord discards an entry strictly below the stored watermark and leaves the stored entry unchanged. Every entry that is not discarded sets the watermark to message_id and stores the submitted mention count.

One Message ACK goes to the caller’s sessions for every submitted entry, including an unchanged one. It reports the resulting message_id, mention_count, and version. It also includes the submitted manual value when any entry is manual or has a positive mention count.

When FiveCord fails to send a Message ACK, the request still succeeds and no Dispatch arrives for that entry. A client reconciles from the entries this route returns or from a new Ready.

Every entry also clears delivered push notifications for its channel through the submitted message_id. FiveCord uses the submitted value even when it discards the entry and keeps a higher stored watermark.

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 current watermark resets the mention count to 0.

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.

A successful acknowledgement can have no corresponding Dispatch.

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.