Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
4.8 KB
Raw Blame
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Read states
description: Per-channel read states and the routes that acknowledge them in bulk.
---

import RouteHeader from '@/components/RouteHeader.astro';

A read state records how far you have read in one channel. Only user accounts can call the routes on this page. To acknowledge a single message, use [Acknowledge message](/http-api/messages/#acknowledge-message).

No HTTP route lists read states. You get them as `read_states` in the [Ready](/gateway/events/#ready) payload, and [Message ACK](/gateway/events/#message-ack) events send changes after that.

## Read state object

### Structure

| Field | Type | Description |
| --- | --- | --- |
| id | snowflake | The ID of the channel |
| mention_count | integer | The number of unread mentions (0-2,147,483,647) |
| last_message_id | ?snowflake | The highest message ID the account has read through |
| last_pin_timestamp | ?ISO8601 timestamp | The time of the last acknowledged pin |
| version? | string | Always `0` |
| flags? | integer | The [read state flags](#read-state-flags), only on threads, forum channels and media channels |

### Example

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

## Read state flags

| Value | Name | Description |
| --- | --- | --- |
| 1 << 0 | IS_GUILD_CHANNEL | The entry belongs to a guild channel |
| 1 << 1 | IS_THREAD | The entry belongs to a thread |

A session that doesn't declare the [`channel_threads` client capability](/http-api/threads/#client-capability) gets no read states for threads, forum channels or media channels.

## Read state acknowledgement object

One entry in the body of [Acknowledge read states](#acknowledge-read-states).

### Structure

| Field | Type | Description |
| --- | --- | --- |
| channel_id | snowflake | The ID of the channel to acknowledge |
| message_id | snowflake | The ID of the message to read through |
| mention_count? | integer | The number of mentions to store (0-2,147,483,647, default `0`) |
| manual? | boolean | Whether to set `last_message_id` to `message_id` even when it is lower |

Without `manual`, an entry whose `message_id` is below the current `last_message_id` changes nothing. With `manual`, a lower `message_id` marks the later messages unread again.

## Bulk read state acknowledgement object

One entry in the body of [Mark channels as read](#mark-channels-as-read).

### Structure

| Field | Type | Description |
| --- | --- | --- |
| channel_id | snowflake | The ID of the channel to acknowledge |
| message_id | snowflake | The ID of the message to read through |

## Acknowledge read states

<RouteHeader method="POST" path="/v1/read-states/ack" />

Applies the [read state acknowledgements](#read-state-acknowledgement-object) and returns the [read states](#read-state-object) that result, in the order you sent them. The response leaves out thread, forum channel and media channel read states that your session can't receive. Sends a [Message ACK](/gateway/events/#message-ack) event to your sessions for each entry. Each entry also clears delivered push notifications for its channel up to the submitted `message_id`.

### JSON body

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

### Response body

| Field | Type | Description |
| --- | --- | --- |
| read_states | array[[read state](#read-state-object) object] | The read states after the acknowledgements |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | response body | The acknowledgements were applied |

The rate limit is 20 requests per 10 seconds, on the `read_state:ack_bulk` bucket.

## Mark channels as read

<RouteHeader method="POST" path="/v1/read-states/ack-bulk" />

Marks each channel as read through `message_id` and sets its mention count to `0`. It works like [Acknowledge read states](#acknowledge-read-states) without `mention_count` or `manual` and returns no body. An entry whose `message_id` is below the current `last_message_id` changes nothing. Sends a [Message ACK](/gateway/events/#message-ack) event to your sessions for each entry. Each entry also clears delivered push notifications for its channel up to the submitted `message_id`.

### JSON body

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

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The acknowledgements were applied |

The rate limit is 20 requests per 10 seconds, on the `read_state:ack_bulk` bucket.