POST
Mark conversation read

Overview

Records that the caller has read all messages in this conversation up to and including upToMessageId. Two things happen server-side:
  1. Every message in this conversation created at or before upToMessageId.createdAt, not sent by the caller, and without an existing readBy entry for the caller, gets a readBy entry appended. The append is atomic and bulk: a single updateMany, not one update per message.
  2. The caller’s participantState[*].unreadCount is reset to 0 and lastReadMessageId is set to upToMessageId.
The newlyReceiptedCount in the response is the count of messages whose readBy was newly added in step 1 — useful for the client to decide whether to broadcast a chat:message:read socket event (a 0 count is a no-op and can be suppressed). Mark-read is also available as a socket event (chat:read) — same service method, same dedup. See Socket events.

Authentication

Bearer <accessToken> required. requireOnboarded middleware applied.

Path parameters

Query parameters

None.

Request body

Example payload

Response — 200 OK

Example response

Error responses

If upToMessageId is a valid ObjectId but doesn’t reference a message in this conversation, the call returns 200 { "newlyReceiptedCount": 0 } (no rows match the bulk update). It does not 404 — the message id is a cursor hint, not a strict reference.

Side effects

  • Bulk readBy append on the matching messages rows (one DB round trip).
  • participantState[caller].unreadCount = 0.
  • participantState[caller].lastReadMessageId = upToMessageId.
  • (When called over the socket transport) a chat:message:read broadcast is emitted to the conversation:<id> room so the sender’s UI can update its delivery indicators in real time. The REST endpoint does not emit the broadcast — callers that want live read-receipts should use the socket event.

See also

curl