nick-doc/03 - API Reference/Chat API.md

---
title: Chat API
tags: [api, chat, reference]
---

# Chat API

> **Last updated:** 2026-05-29 — aligned with code (see [Doc vs Code Audit Report](../09%20-%20Audits/Doc%20vs%20Code%20Audit%20Report%20-%202026-05-29.md))

All chat endpoints live under `/api/chat/*`. The router is [`backend/src/services/chat/chatRoutes.ts`](../../backend/src/services/chat/chatRoutes.ts), controller is `chatController`, service is `ChatService`. Every endpoint requires `Bearer JWT` — the router applies `authenticateToken` globally.

Model: [[Chat]]. Real-time delivery happens over Socket.IO rooms named `chat-<chatId>`. Clients must call `join-chat-room` after connecting. See [[Socket Events]] for `new-message`, `messages-read`, `message-edited`, `message-deleted`, `participants-added`, `participant-removed`, and `user-typing` payloads.

## Rate limits and constraints

| Rule | Value |
| --- | --- |
| Messages per user per minute | **20** |
| Edit window | **15 minutes** after send |
| Maximum message length | **5 000 characters** |

## Conversations

### POST /api/chat

**Description:** Create a generic chat between two or more participants.
**Auth required:** Bearer JWT
**Request body:**
```ts
{
  participantIds: string[];     // 2+ user ids (caller is added automatically)
  type?: "direct" | "group";    // default "direct"
  title?: string;               // group only
  metadata?: Record<string, unknown>;
}
```
**Response 201:** `{ success: true, data: { chat: { _id, participants, type, ... } } }`
**Errors:** `400` need 2+ participants, `404` participant not found.

### POST /api/chat/purchase-request

**Description:** Create (or fetch the existing) chat tied to a specific [[PurchaseRequest]] between buyer and seller. Idempotent.
**Auth required:** Bearer JWT
**Request body:** `{ purchaseRequestId: string; sellerId: string }`
**Response 200/201:** `{ success: true, data: { chat } }`

### POST /api/chat/support

**Description:** Open a support chat. Adds the caller and the support/admin pool. Used by the in-app help widget.
**Auth required:** Bearer JWT
**Request body:** `{ subject?: string; initialMessage?: string }`
**Response 201:** `{ success: true, data: { chat } }`

### GET /api/chat

**Description:** List the caller's chats, ordered by latest message. Includes unread counts.
**Auth required:** Bearer JWT
**Query params:** `page`, `limit`, `type` (`direct` | `group` | `support`)
**Response 200:** `{ success, data: { chats: [...], pagination } }`

### GET /api/chat/stats

**Description:** Aggregate counts (total chats, total messages, total unread).
**Auth required:** Bearer JWT

### GET /api/chat/:id/info

**Description:** Full chat metadata: participants (populated), title, type, created-at, last message, unread per user.
**Auth required:** Bearer JWT (participant)
**Errors:** `403` not a participant, `404` not found.

### PATCH /api/chat/:id/archive

**Description:** Toggle archived state for the caller (per-user flag). Calling this endpoint on an already-archived chat **unarchives** it (toggle semantics).
**Auth required:** Bearer JWT (participant)

> ⚠️ **KNOWN BUG** — The frontend `archiveConversation` helper sends `PUT /api/chat/:id/archive` but the backend route is registered as `PATCH`. The request will receive a `404` until the frontend is corrected to use `PATCH`.

### POST /api/chat/:id/participants

**Description:** Add a participant to a group chat.
**Auth required:** Bearer JWT (creator/admin)
**Request body:** `{ userId: string }`
**Side effects:** Emits `participants-added` on `chat-<id>`.

### DELETE /api/chat/:id/participants/:participantId

**Description:** Remove a participant from a group chat.
**Auth required:** Bearer JWT (creator/admin)
**Side effects:** Emits `participant-removed` on `chat-<id>`.

## Messages

### GET /api/chat/:id/messages

**Description:** Paginated message history (newest first by default).
**Auth required:** Bearer JWT (participant)
**Query params:** `page`, `limit`, `before` (cursor by createdAt)

### POST /api/chat/:id/messages

**Description:** Send a text message.
**Auth required:** Bearer JWT (participant)
**Request body:**
```ts
{
  content: string;
  type?: "text" | "system";       // default "text"
  replyToMessageId?: string;
  metadata?: Record<string, unknown>;
}
```
**Response 201:** `{ success, data: { message } }`
**Side effects:** Emits `new-message` on `chat-<chatId>`; increments unread for other participants.

### POST /api/chat/:id/messages/file

**Description:** Send a message with a binary attachment. Multipart form (`file` field). Maxes follow the [[File API]] limits.
**Auth required:** Bearer JWT (participant)
**Form fields:**
- `file` - the file blob
- `content?` - optional caption
- `replyToMessageId?` - optional

**Response 201:** `{ success, data: { message: { attachments: [{ url, filename, mimeType, size }] } } }`

> ⚠️ **KNOWN BUG** — The frontend `sendFileMessage` function incorrectly posts to `POST /api/chat/:id/messages` (the plain-text endpoint) instead of `POST /api/chat/:id/messages/file`. File uploads are currently broken as a result; the attachment is silently dropped or the request is rejected.

### PATCH /api/chat/:id/messages/read

**Description:** Mark messages as read for the caller. Passing an empty `messageIds` array (or omitting it) marks **all** messages in the chat as read.
**Auth required:** Bearer JWT (participant)
**Response 200:** `{ success, data: { modifiedCount } }`
**Side effects:** Emits `messages-read` on `chat-<id>`.

### PUT /api/chat/:id/messages/:messageId

**Description:** Edit an existing message (author only, within the 15-minute edit window).
**Auth required:** Bearer JWT (message author)
**Request body:** `{ content: string }`
**Side effects:** Emits `message-edited` on `chat-<id>`.

### DELETE /api/chat/:id/messages/:messageId

**Description:** Soft-delete a message (author or admin). The record stays but `deletedAt` is set and `content` is cleared.
**Auth required:** Bearer JWT (author or admin)
**Side effects:** Emits `message-deleted` on `chat-<id>`.

## Typing indicator

Typing indicators are not REST endpoints — clients emit `typing-start` and `typing-stop` over Socket.IO. The server broadcasts `user-typing` to the chat room. Full details in [[Socket Events]].

## Related

- [[Chat]]
- [[Chat Flow]]
- [[File API]] (for attachment uploads)
- [[Notification API]] (for out-of-band notifications when a chat message is received and the user is offline)