POST
Send a message

Overview

Inserts a new message into the conversation and bumps the per-participant unread counters. The request must include a client-generated clientMessageId so retries (e.g. on a flaky network) are idempotent: the server’s unique index on (senderId, clientMessageId) collapses duplicates into a single row. This endpoint is the REST mirror of the chat:message:send socket event. Both transports converge on the same messageService.sendMessage, so validation, dedup, badging, and (Phase 5) push fan-out are identical regardless of which one the client picks. See Socket events for the WebSocket variant and the REST-vs-WS parity discussion. The recipient’s UI is updated either by the socket broadcast (chat:message:new) or by the recipient calling List messages — push notifications are deferred to Phase 5.

Authentication

Bearer <accessToken> required. requireOnboarded middleware applied. Additional service-level gates (checked in this order):
  1. Conversation exists → otherwise 404 NOT_FOUND.
  2. Caller is a participant → otherwise 403 FORBIDDEN.
  3. Conversation status === "ACTIVE" → otherwise 403 CONVERSATION_BLOCKED.
  4. No block exists between sender and the other participant (in either direction) → otherwise 403 CONVERSATION_BLOCKED.

Path parameters

Query parameters

None.

Request body

Media object

Upload the file first via the presign flow with fileType: "CHAT_MEDIA", PUT the bytes to the returned URL, then post the resulting CDN url here.

Example payload — text

Example payload — image (with optional caption)

A captionless media message (text: "") shows a typed placeholder in the inbox preview — 📷 Photo, 🎥 Video, or 📎 File. The chat:message:new socket broadcast carries the full message (including media) so recipients render the attachment live.

Response

201 Created — fresh insert

A new messages row was persisted. The conversation’s lastMessage, lastMessageAt, and the recipient’s unreadCount were bumped. If a WebSocket client is subscribed to conversation:<id>, a chat:message:new event has been broadcast.

200 OK — dedup (idempotent retry)

The same clientMessageId was previously used. The server returns the original message row unchanged. No new row was inserted, no broadcast was emitted, no unread counter was incremented a second time.
Pick the clientMessageId before the first attempt and reuse it on every retry. If you regenerate the id on each retry you defeat the dedup and produce duplicate messages.

Message object

See the Message object schema.

Error responses

Example error — 403 CONVERSATION_BLOCKED

Example error — 400 VALIDATION_FAILED

Side effects

On a fresh insert (201):
  • One messages row inserted.
  • The conversation’s lastMessage, lastMessageAt updated to the new message.
  • Every recipient (every participant except the sender) gets unreadCount += 1.
  • If a WebSocket socket is subscribed to conversation:<id> it receives a chat:message:new broadcast (Socket events page).
  • (Phase 5) A notification.push BullMQ job is enqueued for each muted-off recipient.
On dedup (200): no side effects at all.

See also

curl