إرسال الرسائل

إرسال رسالة صوتية (Voice Note)

إرسال تسجيلات صوتية ذاتية التشغيل على الواتساب.

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

تسجيل الدخول مطلوب

سجل الدخول لاستبدال المعرفات (Instance ID) ورمز الوصول (Access Token) بمعلومات حسابك الحقيقي لاختبار ال API مباشرة.

تسجيل الدخول
اختبار /v2/send/voice
POSTGET

لا توجد معاملات استعلام مطلوبة

هذه النهاية الطرفية لا تتوقع بيانات في الرابط.

توصيات

  • 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.

البارامترات

قم بتهيئة المعاملات المطلوبة للتفاعل مع نقطة النهاية هذه. جميع وسائط الاستعلام والبيانات مدرجة أدناه مع تفاصيلها.

محتوى الطلب

يرسل كـ JSON
string

Unique ID of the WhatsApp session

مثال:
string

API access token

مثال:
string

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

مثال:
string

Publicly accessible HTTPS URL of the audio file

مثال:
string

Filename for the audio note

مثال:
string

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

مثال:
boolean

Automatically transcode to WhatsApp compatible OGG/Opus

مثال:
string—

The ID of the message you are replying to

مثال:

برمج بالذكاء الاصطناعي باستخدام Wawp MCP

MCP READY

قم بربط الـ API مباشرة مع Cursor أو Windsurf أو Claude Desktop، ودع الذكاء الاصطناعي يكتب لك كود الربط وينفذه تلقائياً!

طريقة الربط والإعداد

أمثلة الكود

استخدم أمثلة الكود الجاهزة لدمج واجهة برمجة التطبيقات (API) في مشروعك بسرعة وكفاءة. اختر لغة البرمجة والمكتبة التي تفضلها.

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: طلب غير صالح - معاملات مطلوبة مفقودة");
31    }
32    if (response.status === 400) {
33      console.error("Error 400: طلب غير صالح - الرقم المستهدف في قائمة الحظر الخاصة بك");
34    }
35    if (response.status === 400) {
36      console.error("Error 400: طلب غير صالح - المستلم قام بإلغاء الاشتراك تلقائياً");
37    }
38    if (response.status === 400) {
39      console.error("Error 400: Bad Request - Invalid Number (Egypt)");
40    }
41    if (response.status === 400) {
42      console.error("Error 400: Bad Request - Invalid Number (Saudi Arabia)");
43    }
44    if (response.status === 400) {
45      console.error("Error 400: Bad Request - Invalid Number (Unknown)");
46    }
47    if (response.status === 400) {
48      console.error("Error 400: طلب غير صالح (تنسيق XML)");
49    }
50    if (response.status === 400) {
51      console.error("Error 400: طلب غير صالح (نص عادي)");
52    }
53    if (response.status === 401) {
54      console.error("Error 401: غير مصرح - مفتاح الوصول غير صالح أو مفقود");
55    }
56    if (response.status === 401) {
57      console.error("Error 401: غير مصرح (تنسيق XML)");
58    }
59    if (response.status === 404) {
60      console.error("Error 404: غير موجود - الجلسة غير موجودة");
61    }
62    if (response.status === 404) {
63      console.error("Error 404: غير موجود (تنسيق XML)");
64    }
65    if (response.status === 429) {
66      console.error("Error 429: طلبات كثيرة جداً - تم تجاوز حد المعدل");
67    }
68    if (response.status === 500) {
69      console.error("Error 500: خطأ في الخادم الداخلي - فشل غير متوقع");
70    }
71    if (response.status === 500) {
72      console.error("Error 500: خطأ في الخادم الداخلي (HTML)");
73    }
74    if (response.status === 502) {
75      console.error("Error 502: بوابة غير صالحة - فشل الاتصال بالخادم الرئيسي");
76    }
77    if (response.status === 502) {
78      console.error("Error 502: بوابة غير صالحة (تنسيق XML)");
79    }
80
81    const errorText = await response.text();
82    console.error(`Error ${response.status}: ${errorText}`);
83  })
84  .catch((error) => console.error("Network Error:", error));
عينات تفاعلية
Ln 84, Col 1javascript

الردود المتوقعة

استكشف كافة الردود والنتائج المحتملة من الخادم. قمنا بتوثيق كل كود حالة (Status Code) مع أمثلة للبيانات لتسهيل معالجة الأخطاء والنجاح.

تم إرسال الرسالة بنجاح
النوع:
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": {
  }
}
طلب غير صالح - معاملات مطلوبة مفقودة
غير مصرح - مفتاح الوصول غير صالح أو مفقود
غير موجود - الجلسة غير موجودة
طلبات كثيرة جداً - تم تجاوز حد المعدل
خطأ في الخادم الداخلي - فشل غير متوقع
بوابة غير صالحة - فشل الاتصال بالخادم الرئيسي
الموضوع السابقإرسال حدث (Event)
الموضوع التاليإرسال مقطع فيديو عبر الواتساب

Command Palette

Search for a command to run...