---
title: "Explicitly set Telegram chat read/unread state"
method: POST
path: "/chats/{chat_id}/read-state"
---

# Explicitly set Telegram chat read/unread state

`POST /chats/{chat_id}/read-state`

## Request

- Base URL: `https://gramclaw.com/api/v1`
- URL: `https://gramclaw.com/api/v1/chats/{chat_id}/read-state`
- Auth: HTTP bearer

Requires an explicitly granted write-scoped key and Idempotency-Key. The selected account and chat are resolved together; ambiguous outcomes are not retried. Ordinary history reads remain non-mutating.

## Path parameters

- `chat_id` string, required

## Headers

- `Idempotency-Key` string, required

## Request body

- ReadStateRequest
  - `account_id` string, required: Exact workspace-owned GramClaw compatibility account ID.
  - `unread` boolean, required: true marks the chat unread; false explicitly marks it read.

## Response `200`

The explicit read-state operation was accepted or the exact completed operation was replayed.

## Other responses

- `400`: Invalid account/chat/body or missing idempotency key.
- `403`: Missing write scope or account/chat ownership.
- `409`: Idempotency collision or ambiguous/in-flight mutation.
- `429`: Rate limit exceeded.
- `503`: REST API disabled or scoped session unavailable.

---

[API](https://skmtc.dev/gramclaw/apis/gramclaw-telegram-api.md) · [All operations](https://skmtc.dev/gramclaw/apis/gramclaw-telegram-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gramclaw/apis/gramclaw-telegram-api/revisions/7506dc9c905a?raw)