Send Messages

Send Voice

Voice messages accept OGG/Opus. Required params: instance_id, access_token, chatId, file[url], file[filename], file[mimetype], convert.

POST
https://api.wawp.net/v2/send/voice?access_token=YOUR_ACCESS_TOKEN&chatId=201234567890%40c.us&convert=true&file%5Bfilename%5D=voice.ogg&file%5Bmimetype%5D=audio%2Fogg%3B+codecs%3Dopus&file%5Burl%5D=https%3A%2F%2Fraw.githubusercontent.com%2Frafaelreis-hotmart%2FAudio-Sample-files%2Fmaster%2Fsample.ogg&instance_id=123456789&reply_to=false_111...AAAA

Authentication Required

Login to swap the placeholders with your real Instance ID and Access Token.

Log In
Test /v2/send/voice endpoint
POSTGET

No query parameters required

This endpoint doesn't expect data in the URL.

Best practices

  • Convert audio to the correct format using ffmpeg before sending.

  • Keep voice notes short (under 2 minutes) for better engagement.

The Human Touch: Mastering the Voice Messaging Engine

Voice messages are the most personal way to communicate on WhatsApp, often preferred for their convenience and emotional resonance. The /v2/send/voice endpoint provides a specialized pipeline for delivering high-fidelity audio notes that appear as the native "blue-microphone" messages users expect. Wawp’s voice engine manages the intricate requirements of audio transcoding, MIME-type enforcement, and network buffering to ensure a seamless listening experience.

send voice.png

🏗️ The Intelligent Audio Transcoding Pipeline

WhatsApp is extremely specific about its voice message format. Unlike standard audio file transfers (which appear as documents), true voice notes must be OGG/Opus with specific metadata headers. Wawp simplifies this for you:

  1. Source Evaluation: The engine analyzes the source file from your file[url]. It determines the bitrate, sample rate, and codec.
  2. The "Convert" Logic: When convert: true is set, Wawp initiates a high-performance cloud transcoding process. It takes standard formats like MP3, AAC, or WAV and transforms them into the exact OGG/Opus profile optimized for the WhatsApp mobile app.
  3. MIME-Type Alignment: The engine ensures that the emitted file has the correct audio/ogg; codecs=opus header, which triggers the specialized "Voice Note" UI on the recipient's phone.

🛡️ Strategic Best Practices for Audio Delivery

1. Recording for Quality

To ensure your automated voice messages sound professional:

  • Sample Rate: Record your source audio at 16kHz or 24kHz. WhatsApp’s Opus implementation is optimized for these lower-to-mid ranges, and higher fidelity (like 48kHz) often leads to unnecessary file size increases without a perceptible gain in mobile speaker quality.
  • Mono vs. Stereo: Always use Mono. WhatsApp will down-mix stereo signals anyway, and mono files half the bandwidth requirements for both your server and your user.

2. The Conversion Lifecycle

  • Efficiency Hint: If your source is already OGG/Opus, you can set convert: false. However, we recommend defaulting to true to protect against edge cases where the source metadata might be slightly off-spec, which can cause the play button to fail on some Android devices.
  • Transcoding Latency: Cloud transcoding adds a small amount of latency (typically 1–3 seconds) to the processing time. Factor this into your application's timeout logic.

3. UX and Accessibility

Voice messaging isn't just about the audio; it's about the context.

  • Typing Indicator: Before sending a voice note, call the /v2/send/start-typing endpoint. This creates the "Typing..." or "Recording audio..." status on the recipient's phone, making the message feel more organic and less like an automated broadcast.
  • Interactive Feedback: In your frontend, show a "Transcoding..." spinner after the user submits an audio file to manage expectations during the cloud processing phase.

🧩 Advanced Use Cases

Voice-Powered Notification Banners

Instead of a text-based order update, send a 5-second voice note saying, "Hi there! Your order is on the way." The personal touch significantly increases engagement and brand loyalty in localized markets.

Interactive Voice Response (IVR) for WhatsApp

Build a support bot where users can send voice notes for queries. Your backend can transcribe the audio using an AI service, and then respond with a pre-recorded voice note via Wawp, creating a truly conversational voice interface.

🛠️ Common Pitfalls and Solutions

  • Mismatched Mime-Types: Providing a .mp3 extension with an audio/ogg mimetype will often cause the engine to return a Bad Request. Ensure your file[filename] and file[mimetype] align with the actual source file on your server.
  • Corrupted Headers: Some audio recorders produce OGG files with non-standard page sizes. If a voice note arrives but won't play, it’s a sign that the headers are corrupted. Enabling convert: true almost always fixes this by rebuilding the file from the raw audio stream.
  • Volume Normalization: Automated voices can sometimes be too loud or too quiet. We recommend normalizing your source clips to -3dB to ensure consistent volume regardless of the recipient's phone settings.

Summary of Capabilities:

  • Deliver native WhatsApp "Voice Notes" (OGG/Opus) from any public HTTPS URL.
  • Full support for cloud-based transcoding from MP3, AAC, and WAV via the convert flag.
  • Precise integration with threading and replies using the reply_to parameter.
  • Consistent success reporting with unique message_id generation.
  • Optimized for low-bandwidth mobile consumption while maintaining high vocal clarity.

Request Parameters

Configure the parameters required to interact with this endpoint. All query and body arguments are listed below with their details.

Request Body

Sent as a JSON object
string

Unique ID of the WhatsApp session

Example:
string

API access token

Example:
string

Recipient's WhatsApp ID (JID). Supports Individuals (@c.us), Groups (@g.us), and Newsletters (@newsletter).

Example:
string

Publicly accessible HTTPS URL of the audio file

Example:
string

Filename for the audio note

Example:
string

MIME type (audio/ogg; codecs=opus recommended)

Example:
boolean

Automatically transcode to WhatsApp compatible OGG/Opus

Example:
string—

The ID of the message you are replying to

Example:

Request Samples

Use these ready-to-go code snippets to integrate our API into your project quickly and efficiently. Choose your preferred language and library.

1const baseUrl = "https://api.wawp.net";
2const endpoint = "/v2/send/voice";
3const params = new URLSearchParams({
4  "instance_id": "123456789",
5  "access_token": "YOUR_ACCESS_TOKEN"
6}).toString();
7const body = {
8  "chatId": "201234567890@c.us",
9  "file[url]": "https://raw.githubusercontent.com/rafaelreis-hotmart/Audio-Sample-files/master/sample.ogg",
10  "file[filename]": "voice.ogg",
11  "file[mimetype]": "audio/ogg; codecs=opus",
12  "convert": "true",
13  "reply_to": "false_111...AAAA"
14};
15
16fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
17  method: "POST",
18  headers: { "Content-Type": "application/json" },
19  body: JSON.stringify(body)
20})
21  .then(async (response) => {
22    if (response.ok) {
23      const data = await response.json();
24      console.log("Success:", data);
25      return data;
26    }
27    
28    // Error Handling
29    if (response.status === 400) {
30      console.error("Error 400: Bad Request - Missing Required Parameter(s)");
31    }
32    if (response.status === 400) {
33      console.error("Error 400: Bad Request - Invalid Number (Egypt)");
34    }
35    if (response.status === 400) {
36      console.error("Error 400: Bad Request - Invalid Number (Saudi Arabia)");
37    }
38    if (response.status === 400) {
39      console.error("Error 400: Bad Request - Invalid Number (Unknown)");
40    }
41    if (response.status === 400) {
42      console.error("Error 400: Bad Request (XML Format)");
43    }
44    if (response.status === 400) {
45      console.error("Error 400: Bad Request (Plain Text)");
46    }
47    if (response.status === 401) {
48      console.error("Error 401: Unauthorized - Invalid or Missing Access Token");
49    }
50    if (response.status === 401) {
51      console.error("Error 401: Unauthorized (XML Format)");
52    }
53    if (response.status === 404) {
54      console.error("Error 404: Not Found - Session Does Not Exist");
55    }
56    if (response.status === 404) {
57      console.error("Error 404: Not Found (XML Format)");
58    }
59    if (response.status === 429) {
60      console.error("Error 429: Too Many Requests - Rate Limit Exceeded");
61    }
62    if (response.status === 500) {
63      console.error("Error 500: Internal Server Error - Unexpected Failure");
64    }
65    if (response.status === 500) {
66      console.error("Error 500: Internal Server Error (HTML)");
67    }
68    if (response.status === 502) {
69      console.error("Error 502: Bad Gateway - Connection Failed to Upstream");
70    }
71    if (response.status === 502) {
72      console.error("Error 502: Bad Gateway (XML Format)");
73    }
74
75    const errorText = await response.text();
76    console.error(`Error ${response.status}: ${errorText}`);
77  })
78  .catch((error) => console.error("Network Error:", error));
Interactive Samples
Ln 78, Col 1javascript

Expected Responses

Explore all possible responses and outcomes from the server. We have documented each status code with data examples to make success and error handling easier.

Message Sent Successfully
Type:
application/json
object *
string *
object *
number *
boolean *
string *
string *
number *
string *
string *
string *
boolean *
number *
boolean *
boolean *
boolean *
boolean *
boolean *
array *
array *
array *
boolean *
array *

Example

{
"_data": {
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
  "viewed": false,
  "body": "BASE64_IMAGE_DATA",
  "type": "image",
  "t": 1759108866,
  "from": {
    "server": "c.us",
    "user": "111111111111",
    "_serialized": "111111111111@c.us"
    },
  "to": {
    "server": "c.us",
    "user": "000000000000",
    "_serialized": "000000000000@c.us"
    },
  "ack": 0,
  "isNewMsg": true,
  "star": false,
  "kicNotified": false,
  "caption": "Here's your requested image.",
  "deprecatedMms3Url": "https://example.com/media-url",
  "directPath": "/media/direct/path/example",
  "mimetype": "image/jpeg",
  "filehash": "FILE_HASH_PLACEHOLDER",
  "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
  "size": 192487,
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "mediaKeyTimestamp": 1759108865,
  "streamable": false,
  "mediaHandle": null,
  "isFromTemplate": false,
  "pollInvalidated": false,
  "isSentCagPollCreation": false,
  "latestEditMsgKey": null,
  "latestEditSenderTimestampMs": null,
  "mentionedJidList": {
    },
  "groupMentions": {
    },
  "isEventCanceled": false,
  "eventInvalidated": false,
  "isVcardOverMmsDocument": false,
  "isForwarded": false,
  "isQuestion": false,
  "questionReplyQuotedMessage": null,
  "questionResponsesCount": 0,
  "readQuestionResponsesCount": 0,
  "labels": {
    },
  "hasReaction": false,
  "disappearingModeInitiator": "chat",
  "disappearingModeTrigger": "chat_settings",
  "productHeaderImageRejected": false,
  "lastPlaybackProgress": 0,
  "isDynamicReplyButtonsMsg": false,
  "isCarouselCard": false,
  "parentMsgId": null,
  "callSilenceReason": null,
  "isVideoCall": false,
  "callDuration": null,
  "callCreator": null,
  "callParticipants": null,
  "isCallLink": null,
  "callLinkToken": null,
  "isMdHistoryMsg": false,
  "stickerSentTs": 0,
  "lastUpdateFromServerTs": 0,
  "invokedBotWid": null,
  "bizBotType": null,
  "botResponseTargetId": null,
  "botPluginType": null,
  "botPluginReferenceIndex": null,
  "botPluginSearchProvider": null,
  "botPluginSearchUrl": null,
  "botPluginSearchQuery": null,
  "botPluginMaybeParent": false,
  "botReelPluginThumbnailCdnUrl": null,
  "botMessageDisclaimerText": null,
  "botMsgBodyType": null,
  "requiresDirectConnection": false,
  "bizContentPlaceholderType": null,
  "hostedBizEncStateMismatch": false,
  "senderOrRecipientAccountTypeHosted": false,
  "placeholderCreatedWhenAccountIsHosted": false,
  "galaxyFlowDisabled": false,
  "links": {
    }
  },
"mediaKey": "MEDIA_KEY_PLACEHOLDER",
"id": {
  "fromMe": true,
  "remote": "000000000000@c.us",
  "id": "MSG_ID_123456",
  "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
"ack": 0,
"hasMedia": true,
"body": "Here's your requested image.",
"type": "image",
"timestamp": 1759108866,
"from": "111111111111@c.us",
"to": "000000000000@c.us",
"deviceType": "android",
"isForwarded": false,
"forwardingScore": 0,
"isStatus": false,
"isStarred": false,
"fromMe": true,
"hasQuotedMsg": false,
"hasReaction": false,
"vCards": {
  },
"mentionedIds": {
  },
"groupMentions": {
  },
"isGif": false,
"links": {
  }
}
Bad Request - Missing Required Parameter(s)
Unauthorized - Invalid or Missing Access Token
Not Found - Session Does Not Exist
Too Many Requests - Rate Limit Exceeded
Internal Server Error - Unexpected Failure
Bad Gateway - Connection Failed to Upstream
Previous TopicSend Event
Next TopicSend Video

Command Palette

Search for a command to run...