Mark messages as read

POST /v1/{phone_number_id}/messages doubles as both the outbound-send endpoint and the read-receipt endpoint — exactly like Meta’s WhatsApp Cloud API. To mark an inbound message as read, send a body with status: "read" and the inbound wamid you received from your webhook.

The double-tick on the sender’s phone turns blue.

cURL

curl -X POST \
  https://api.kirim.chat/v1/$PHONE_ID/messages \
  -H "Authorization: Bearer $KIRIM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "status": "read",
    "message_id": "wamid.HBgNNjI4MTIzNDU2Nzg5FQIAEhggMUE5MDM1QzVDMUYxQTAyRkVCNzZDQjVDMjFFRDQzNTUA"
  }'

TypeScript SDK

import { Kirim } from '@kirimdev/sdk'

const kirim = new Kirim({ apiKey: process.env.KIRIM_KEY! })
const phone = kirim.phoneNumbers(process.env.PHONE_ID!)

await phone.messages.markAsRead('wamid.HBgN…')

Note

message_id here is the Meta-native wamid (e.g. wamid.HBgN…) that arrived in your inbound webhook — NOT a Kirim msg_* external id. Meta itself uses wamids for this operation; we accept them directly so you don’t need a translate round-trip.

With typing indicator

Add typing_indicator: { type: "text" } to also show a typing bubble to the sender alongside the receipt. Meta auto-dismisses it on your first outbound message or after ~25 seconds.

cURL

curl -X POST \
  https://api.kirim.chat/v1/$PHONE_ID/messages \
  -H "Authorization: Bearer $KIRIM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "status": "read",
    "message_id": "wamid.HBgN…",
    "typing_indicator": { "type": "text" }
  }'

TypeScript SDK

import { Kirim } from '@kirimdev/sdk'

const kirim = new Kirim({ apiKey: process.env.KIRIM_KEY! })
const phone = kirim.phoneNumbers(process.env.PHONE_ID!)

await phone.messages.markAsRead('wamid.HBgN…', { typing: true })

Caution

Only show the typing indicator if you actually intend to respond. Leaving it hanging until Meta auto-dismisses produces a poor UX — the recipient sees you “typing” for 25 seconds with no reply.

Response

{
  "data": {
    "id": "msg_01HXYZABCDEFGHJKMNPQRSTVWX",
    "object": "message",
    "status": "read",
    "message_id": "wamid.HBgN…"
  },
  "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}

id is the Kirim external id of the inbound message row that was flipped to read locally. message_id echoes back the wamid you sent so retries can be correlated.

Idempotency

Safe to retry. A second call against a message that’s already in read state returns the same 200 payload without making another request to Meta — same shape regardless of whether the first call actually sent the receipt or not.

Errors

Status	Code	When
404	resource_not_found	message_id (wamid) unknown to your org, or belongs to a different account
400	invalid_field_value	The wamid resolves to an outbound message — only inbound messages can be marked as read
502	whatsapp_upstream_error	Meta accepted the request but the receipt is past the 7-day window or another upstream limit

Note

This is different from the inbox “mark as read” UI action. The inbox uses an internal endpoint that only clears the local unread counter — it deliberately does not send a receipt because opening a conversation thread is not the same as a human having read the message. The Public API endpoint documented here always sends the receipt.

See also

• API Reference — Send a WhatsApp message (see the Read receipt request-body tab)
• Receive messages — where you get the wamid to mark