Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(api): list mentions, quotedMessageId and bulk ptt on media sends

Yudhi Armyndharis40b130b95ab8
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index c55c2902d..508bb6cbd 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -1815,15 +1815,16 @@ Send an image (by URL or base64) with an optional caption.
**Request body** — `SendMediaMessageDto`
-| Field | Type | Required | Constraints | Description |
-| --------------- | ------ | ----------- | ------------------------------------- | ---------------------------------------------------------------------------------------- |
-| chatId | string | Yes | non-empty | Target chat |
-| url | string | Conditional | URL; required when `base64` is absent | http/https media URL (SSRF-guarded; a blocked internal or unreachable URL maps to `400`) |
-| base64 | string | Conditional | string; required when `url` is absent | Base64 media data (capped to the media byte limit) |
-| mimetype | string | Conditional | string; required when using `base64` | MIME type of the media |
-| filename | string | No | max 255 | File name |
-| caption | string | No | max 1024 | Caption text |
-| quotedMessageId | string | No | non-empty | Quote an earlier message, making this a reply — see [Quoted sends](#quoted-sends) |
+| Field | Type | Required | Constraints | Description |
+| --------------- | -------- | ----------- | ------------------------------------- | ---------------------------------------------------------------------------------------- |
+| chatId | string | Yes | non-empty | Target chat |
+| url | string | Conditional | URL; required when `base64` is absent | http/https media URL (SSRF-guarded; a blocked internal or unreachable URL maps to `400`) |
+| base64 | string | Conditional | string; required when `url` is absent | Base64 media data (capped to the media byte limit) |
+| mimetype | string | Conditional | string; required when using `base64` | MIME type of the media |
+| filename | string | No | max 255 | File name |
+| caption | string | No | max 1024 | Caption text |
+| mentions | string[] | No | array of WIDs | WIDs to @mention in the caption. See **Mentions** above |
+| quotedMessageId | string | No | non-empty | Quote an earlier message, making this a reply — see [Quoted sends](#quoted-sends) |
```json
{ "chatId": "[email protected]", "url": "https://example.com/image.jpg", "caption": "Check out this image!" }
@@ -1849,7 +1850,7 @@ Send a video (by URL or base64) with an optional caption. Uses the same `SendMed
| --------- | ------ | ----------- |
| sessionId | string | Session ID |
-**Request body** — `SendMediaMessageDto` (fields `chatId`, `url`, `base64`, `mimetype`, `filename`, `caption`, `quotedMessageId` — see `send-image`)
+**Request body** — `SendMediaMessageDto` (fields `chatId`, `url`, `base64`, `mimetype`, `filename`, `caption`, `mentions`, `quotedMessageId` — see `send-image`)
```json
{ "chatId": "[email protected]", "url": "https://example.com/clip.mp4", "caption": "video" }
@@ -1865,7 +1866,7 @@ Send a video (by URL or base64) with an optional caption. Uses the same `SendMed
#### POST /api/sessions/:sessionId/messages/send-audio
-Send an audio message (by URL or base64). Uses `SendAudioMessageDto`. A `caption` is accepted by the DTO but not persisted for audio. Set `ptt: true` to send a real WhatsApp **voice note** (microphone bubble + waveform) instead of a plain audio file. `ptt` is a JSON boolean, exclusive to this endpoint, and — because voice notes require `audio/ogg; codecs=opus` — the server defaults the mimetype to that when you set `ptt` without one; for reliable playback (especially on the Baileys engine, which does not transcode) supply OGG/Opus bytes. A `ptt` voice note is stored as message `type: "voice"`.
+Send an audio message (by URL or base64). Uses `SendAudioMessageDto`. A `caption` is accepted by the DTO but not persisted for audio. Set `ptt: true` to send a real WhatsApp **voice note** (microphone bubble + waveform) instead of a plain audio file. `ptt` is a JSON boolean, exclusive to this endpoint and to `audio` items of `send-bulk`, and — because voice notes require `audio/ogg; codecs=opus` — the server defaults the mimetype to that when you set `ptt` without one; for reliable playback (especially on the Baileys engine, which does not transcode) supply OGG/Opus bytes. A `ptt` voice note is stored as message `type: "voice"`.
**Auth:** API key (OPERATOR)
@@ -1875,7 +1876,7 @@ Send an audio message (by URL or base64). Uses `SendAudioMessageDto`. A `caption
| --------- | ------ | ----------- |
| sessionId | string | Session ID |
-**Request body** — `SendAudioMessageDto` (all `SendMediaMessageDto` fields — `chatId`, `url`, `base64`, `mimetype`, `filename`, `caption` — plus optional `ptt` boolean)
+**Request body** — `SendAudioMessageDto` (all `SendMediaMessageDto` fields — `chatId`, `url`, `base64`, `mimetype`, `filename`, `caption`, `mentions`, `quotedMessageId` — plus optional `ptt` boolean)
```json
{ "chatId": "[email protected]", "url": "https://example.com/voice.ogg", "mimetype": "audio/ogg", "ptt": true }
@@ -1901,7 +1902,7 @@ Send a document/file (by URL or base64). Uses `SendMediaMessageDto`; `filename`
| --------- | ------ | ----------- |
| sessionId | string | Session ID |
-**Request body** — `SendMediaMessageDto` (fields `chatId`, `url`, `base64`, `mimetype`, `filename`, `caption`, `quotedMessageId` — see `send-image`)
+**Request body** — `SendMediaMessageDto` (fields `chatId`, `url`, `base64`, `mimetype`, `filename`, `caption`, `mentions`, `quotedMessageId` — see `send-image`)
```json
{
@@ -2008,7 +2009,7 @@ Send a sticker (by URL or base64; typically webp). Reuses `SendMediaMessageDto`.
| --------- | ------ | ----------- |
| sessionId | string | Session ID |
-**Request body** — `SendMediaMessageDto` (fields `chatId`, `url`, `base64`, `mimetype`, `filename`, `caption`, `quotedMessageId` — see `send-image`)
+**Request body** — `SendMediaMessageDto` (fields `chatId`, `url`, `base64`, `mimetype`, `filename`, `caption`, `mentions`, `quotedMessageId` — see `send-image`)
```json
{ "chatId": "[email protected]", "url": "https://example.com/sticker.webp", "mimetype": "image/webp" }
@@ -2296,7 +2297,7 @@ Send messages to multiple recipients as an async batch — returns immediately a
| messages | BulkMessageItemDto[] | Yes | array, max 100, nested-validated | The batch items (see below); exact duplicate entries (same `chatId`, `type`, `content` and `variables`) are collapsed before processing, first occurrence wins, order preserved; distinct messages to the same `chatId` are all sent |
| options | BulkMessageOptionsDto | No | nested-validated | Pacing/error options (see below) |
-Each `BulkMessageItemDto`: `{ chatId: string, type: 'text'|'image'|'video'|'audio'|'document', content: BulkMessageContentDto, variables?: Record<string,string> }`. `content` (all fields optional, nested-validated): `text?: string`, `image?`/`video?`/`audio?`/`document?`: `{ url?, base64?, mimetype?, filename? }`, `caption?: string`, `mentions?: string[]` (per item; a batch fans out to many chats, and a WID is only taggable in a chat the participant is in).
+Each `BulkMessageItemDto`: `{ chatId: string, type: 'text'|'image'|'video'|'audio'|'document', content: BulkMessageContentDto, variables?: Record<string,string> }`. `content` (all fields optional, nested-validated): `text?: string`, `image?`/`video?`/`audio?`/`document?`: `{ url?, base64?, mimetype?, filename?, ptt? }` (`ptt` applies to `audio` only), `caption?: string`, `mentions?: string[]` (per item; a batch fans out to many chats, and a WID is only taggable in a chat the participant is in).
`BulkMessageOptionsDto`: `{ delayBetweenMessages?: number (1000–60000, default 3000), randomizeDelay?: boolean (default true), stopOnError?: boolean (default false) }`.