feat: send true WhatsApp voice notes (PTT) via send-audio, bulk, and MCP (#559)

Adds an opt-in `ptt` boolean so send-audio, bulk send, and the MessageSendAudio MCP tool can send a true WhatsApp voice note (mic bubble + waveform) on both engines. Backward compatible (default off); outbound voice notes persist as type 'voice'; server defaults the mimetype to audio/ogg; codecs=opus when ptt is set without one; no transcoding. SDK types + docs updated. Fulfils FR-MSG-004. (OpenWA-n8n #13)

Author: rmyndharis

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Send true WhatsApp voice notes (PTT).** The `send-audio` endpoint, bulk send, and the `MessageSendAudio` agent tool now accept an optional `ptt` boolean; when set, the message is delivered as a real voice note — the microphone bubble with a waveform — instead of a plain audio file, on both the Baileys and whatsapp-web.js engines. Voice notes require `audio/ogg; codecs=opus` audio, so the server defaults the mimetype to that when `ptt` is set without one (supply OGG/Opus bytes for reliable playback), and stores the message as `type: "voice"`. Fulfills FR-MSG-004. (OpenWA-n8n #13)
+
 ### Fixed
 
 - **Sending to — or operating on — a WhatsApp Channel (newsletter) no longer logs internal errors.** On the whatsapp-web.js engine a channel JID (`…@newsletter`) resolves to a `Channel`, which has none of the per-chat operations; the gateway now skips those for channels instead of throwing. The typing indicator that precedes a send, the typing/recording presence endpoint and its MCP tool, mark-unread, and delete-chat now cleanly no-op for a channel (presence does nothing; mark-unread and delete-chat report no change) rather than emitting an internal `TypeError`. Fetching chat labels for a channel previously failed with HTTP 500 — it now returns an empty list. Direct chats, groups, and broadcast lists are unaffected. (#554) Thanks @DanielOberlechner.

docs/06-api-specification.md

@@ -996,7 +996,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/voice message (by URL or base64). Uses `SendMediaMessageDto`. A `caption` is accepted by the DTO but not persisted for 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"`.
 
 **Auth:** API key (OPERATOR)
 
@@ -1006,10 +1006,10 @@ Send an audio/voice message (by URL or base64). Uses `SendMediaMessageDto`. A `c
 | --- | --- | --- |
 | sessionId | string | Session ID |
 
-**Request body** — `SendMediaMessageDto` (fields `chatId`, `url`, `base64`, `mimetype`, `filename`, `caption` — see `send-image`)
+**Request body** — `SendAudioMessageDto` (all `SendMediaMessageDto` fields — `chatId`, `url`, `base64`, `mimetype`, `filename`, `caption` — plus optional `ptt` boolean)
 
 ```json
-{ "chatId": "628123456789@c.us", "url": "https://example.com/voice.ogg", "mimetype": "audio/ogg" }
+{ "chatId": "628123456789@c.us", "url": "https://example.com/voice.ogg", "mimetype": "audio/ogg", "ptt": true }
 ```
 
 **Response** `201`

docs/07-api-collection.md

@@ -278,13 +278,13 @@ curl -X POST "$BASE/api/sessions/my-session/messages/send-video" \
 
 #### POST /api/sessions/:sessionId/messages/send-audio
 
-Send an audio/voice message by URL or base64.
+Send an audio message by URL or base64. Add `"ptt": true` to send a real WhatsApp voice note (mic bubble + waveform); the server defaults the mimetype to `audio/ogg; codecs=opus` when `ptt` is set without one.
 
 ```bash
 curl -X POST "$BASE/api/sessions/my-session/messages/send-audio" \
   -H "X-API-Key: $API_KEY" \
   -H "Content-Type: application/json" \
-  -d '{ "chatId": "628123456789@c.us", "url": "https://example.com/voice.ogg", "mimetype": "audio/ogg" }'
+  -d '{ "chatId": "628123456789@c.us", "url": "https://example.com/voice.ogg", "mimetype": "audio/ogg", "ptt": true }'
 ```
 
 #### POST /api/sessions/:sessionId/messages/send-document

sdk/javascript/README.md

@@ -33,6 +33,10 @@ console.log(result.messageId);
 
 CommonJS consumers use `require('@rmyndharis/openwa')` identically.
 
+## Messaging
+
+> Voice notes: pass `ptt: true` to `sendAudio` to send a real WhatsApp voice note (PTT). Supply `audio/ogg; codecs=opus` audio for reliable playback; the server defaults the mimetype to that when `ptt` is set without one.
+
 ## Errors
 
 Non-2xx responses throw a typed `OpenWAApiError` subclass

sdk/javascript/src/types.ts

@@ -108,6 +108,8 @@ export interface SendMediaRequest {
   filename?: string;
   /** Max 1024 chars. */
   caption?: string;
+  /** Audio only: send as a WhatsApp voice note (PTT). Server defaults mimetype to audio/ogg; codecs=opus. */
+  ptt?: boolean;
 }
 
 export interface SendLocationRequest {

sdk/php/README.md

@@ -44,6 +44,10 @@ $client = new Client([
 ]);
 ```
 
+## Messaging
+
+> Voice notes: pass `'ptt' => true` to `sendAudio` to send a real WhatsApp voice note (PTT). Supply `audio/ogg; codecs=opus` audio for reliable playback; the server defaults the mimetype to that when `ptt` is set without one.
+
 ## Errors
 
 A non-2xx response throws a typed `OpenWA\Exceptions\OpenWAApiException` subclass —

sdk/python/README.md

@@ -45,6 +45,10 @@ import httpx
 client = OpenWAClient(base_url="…", api_key="…", transport=httpx.MockTransport(handler))
 ```
 
+## Messaging
+
+> Voice notes: pass `ptt=True` inside the body dict to `send_audio` to send a real WhatsApp voice note (PTT). Supply `audio/ogg; codecs=opus` audio for reliable playback; the server defaults the mimetype to that when `ptt` is set without one.
+
 ## Errors
 
 A non-2xx response raises a typed `OpenWAApiError` subclass — `OpenWAAuthError` (401),

sdk/python/openwa/types.py

@@ -107,6 +107,7 @@ class SendMediaRequest(TypedDict, total=False):
     mimetype: str
     filename: str
     caption: str
+    ptt: bool  # audio only: send as a WhatsApp voice note (PTT)
 
 
 class SendLocationRequest(TypedDict, total=False):

src/core/agent-tools/tools/message.tools.ts

@@ -157,6 +157,7 @@ export function messageTools(message: MessageService): ToolDescriptor[] {
         mimetype: z.string().optional().describe('MIME type (required when using base64)'),
         filename: z.string().max(255).optional(),
         caption: z.string().max(1024).optional(),
+        ptt: z.boolean().optional().describe('Send as a WhatsApp voice note (PTT)'),
       }),
       handler: (input: {
         sessionId: string;
@@ -166,6 +167,7 @@ export function messageTools(message: MessageService): ToolDescriptor[] {
         mimetype?: string;
         filename?: string;
         caption?: string;
+        ptt?: boolean;
       }) =>
         message.sendAudio(input.sessionId, {
           chatId: input.chatId,
@@ -174,6 +176,7 @@ export function messageTools(message: MessageService): ToolDescriptor[] {
           mimetype: input.mimetype,
           filename: input.filename,
           caption: input.caption,
+          ptt: input.ptt,
         }),
     },
     {

src/engine/adapters/baileys.adapter.spec.ts

@@ -1409,6 +1409,20 @@ describe('BaileysAdapter media sends', () => {
     });
   });
 
+  it('sendAudioMessage with ptt sends a voice note (ptt:true)', async () => {
+    const adapter = await ready();
+    await adapter.sendAudioMessage('628111@s.whatsapp.net', {
+      mimetype: 'audio/ogg; codecs=opus',
+      data: Buffer.from([1]),
+      ptt: true,
+    });
+    expect(fakeSock.sendMessage).toHaveBeenCalledWith('628111@s.whatsapp.net', {
+      audio: Buffer.from([1]),
+      mimetype: 'audio/ogg; codecs=opus',
+      ptt: true,
+    });
+  });
+
   it('sendStickerMessage sends the sticker buffer', async () => {
     const adapter = await ready();
     await adapter.sendStickerMessage('628111@s.whatsapp.net', { mimetype: 'image/webp', data: Buffer.from([7]) });