---
title: "Mark a WhatsApp message as read"
method: POST
path: "/v1/whatsapp/messages/{message_id}/read"
tags: ["whatsapp-messages"]
---

# Mark a WhatsApp message as read

`POST /v1/whatsapp/messages/{message_id}/read`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/whatsapp/messages/{message_id}/read`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Marks an inbound WhatsApp message as read, showing the contact the blue
ticks. WhatsApp also marks every earlier message in that conversation read.
This does not change the workspace inbox unread count. Use the conversation
update endpoint with `read` to acknowledge messages in the inbox.

Pass `typing_indicator: true` to show a typing indicator as well. WhatsApp
clears it when you send your next message, or after 25 seconds, whichever
comes first, and there is no call to clear it early, so ask for one only
when you are about to reply. WhatsApp cannot show a typing indicator without
a read receipt, so both arrive together.

The acknowledgement is sent asynchronously: a `202` means Bird accepted the
request, not that WhatsApp has shown it. Nothing reports back, because
WhatsApp publishes no delivery, status or failure callback for an
acknowledgement, so there is nothing to poll and no webhook event.
Repeating the call is safe, and each call restarts the 25-second typing
window. To refresh the indicator, send a fresh `Idempotency-Key` or none at
all: a replayed key answers from the stored response without acknowledging
anything again.

Only an inbound message can be marked read. WhatsApp allows this for 30
days after receipt, but Bird keeps the provider id a receipt needs for 15
days, so a message older than that answers `404`. A message Bird sent, or
one that never reached WhatsApp, answers `422`.

## Path parameters

- `message_id` string, required

## Headers

- `Idempotency-Key` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Request body

- WhatsAppReadReceiptRequest: What to acknowledge on the inbound message. An absent body and `{}` mean the same thing: mark the message read and show nothing.
  - `typing_indicator` boolean: Show a typing indicator to the contact as well as marking the message read. WhatsApp clears it when you send your next message, or after 25 seconds, whichever comes first. Only ask for one if you are about to reply.

## Response `202`

Acknowledgement accepted for asynchronous delivery.

- WhatsAppReadReceipt: The acknowledgement Bird accepted. There is no status to poll afterwards: WhatsApp reports nothing about a read receipt.
  - `typing_indicator` boolean, required: Whether a typing indicator was requested alongside the read receipt.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)