Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
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.mdindex 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) }`.