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

إرسال رسالة صوتية

تقبل الرسائل الصوتية OGG/Opus. المعلمات المطلوبة: 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

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

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

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

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

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

توصيات

  • قم بتحويل الصوت إلى التنسيق الصحيح باستخدام ffmpeg قبل الإرسال.

  • اجعل الملاحظات الصوتية قصيرة (أقل من دقيقتين) لتفاعل أفضل.

اللمسة الإنسانية: إتقان محرك الرسائل الصوتية

الرسائل الصوتية هي الطريقة الأكثرشخصية للتواصل على واتساب، وغالبًا ما تُفضل لراحتها ورنينها العاطفي. توفر نقطة نهاية /v2/send/voice مسارًا متخصصًا لتقديم ملاحظات صوتية عالية الدقة تظهر كرسائل "الميكروفون الأزرق" الأصلية التي يتوقعها المستخدمون. يدير محرك صوت Wawp المتطلبات المعقدة لفك تشفير الصوت، وفرض نوع MIME، وتخزين الشبكة المؤقت لضمان تجربة استماع سلسة.

إرسال صوت

🏗️ محرك فك تشفير الصوت الذكي سحابيًا

واتساب محدد للغاية بشأن تنسيق الرسائل الصوتية الخاصة به. على عكس عمليات نقل ملفات الصوت القياسية (التي تظهر كمستندات)، يجب أن تكون الملاحظات الصوتية الحقيقية بتنسيق OGG/Opus مع رؤوس بيانات وصفية محددة. يسهل Wawp ذلك عليك:

  1. تقييم المصدر: يقوم المحرك بتحليل ملف المصدر من file[url] الخاص بك. ويحدد معدل البت ومعدل العينة وبرنامج الترميز.
  2. منطق "التحويل" (Convert Logic): عند تعيين convert: true، يبدأ Wawp عملية فك تشفير سحابية عالية الأداء. يأخذ التنسيقات القياسية مثل MP3 أو AAC أو WAV ويحولها إلى ملف OGG/Opus الدقيق المحسن لتطبيق واتساب للجوال.
  3. محاذاة نوع MIME: يضمن المحرك أن الملف الصادر لديه رأس audio/ogg; codecs=opus الصحيح، والذي يطلق واجهة مستخدم "ملاحظة صوتية" المتخصصة على هاتف المستلم.

🛡️ أفضل الممارسات الاستراتيجية لتسليم الصوت

1. التسجيل من أجل الجودة

لضمان سماع رسائلك الصوتية المؤتمتة بشكل احترافي:

  • معدل العينة: سجل صوت المصدر الخاص بك بتردد 16 كيلو هرتز أو 24 كيلو هرتز. تم تحسين تنفيذ Opus في واتساب لهذه النطاقات المنخفضة إلى المتوسطة، وغالبًا ما تؤدي الدقة الأعلى (مثل 48 كيلو هرتز) إلى زيادات غير ضرورية في حجم الملف دون مكاسب ملموسة في جودة سماعة الهاتف المحمول.
  • أحادية مقابل ستيريو (Mono vs. Stereo): استخدم دائمًا Mono. سيقوم واتساب بخلط إشارات الستيريو إلى أحادية على أي حال، والملفات الأحادية تقلل من متطلبات النطاق الترددي لكل من خادمك ومستخدمك.

2. دورة حياة التحويل

  • تلميح الكفاءة: إذا كان المصدر الخاص بك بالفعل OGG/Opus، يمكنك تعيين convert: false. ومع ذلك، نوصي بالالتزام بـ true للحماية من الحالات الحدودية حيث قد تكون البيانات الوصفية للمصدر غير دقيقة قليلاً، مما قد يؤدي إلى فشل زر التشغيل على بعض أجهزة Android.
  • تأخير فك التشفير: يضيف فك التشفير السحابي قدرًا صغيرًا من التأخير (عادةً 1-3 ثوانٍ) إلى وقت المعالجة. ضع ذلك في الاعتبار في منطق المهلة الخاص بتطبيقك.

3. تجربة المستخدم وسهولة الوصول

المراسلة الصوتية لا تتعلق فقط بالصوت؛ بل تتعلق بالسياق.

  • مؤشر الكتابة: قبل إرسال ملاحظة صوتية، استدعِ نقطة النهاية /v2/send/start-typing. هذا ينشئ حالة "جاري الكتابة..." أو "جاري تسجيل صوت..." على هاتف المستلم، مما يجعل الرسالة تبدو أكثر حيوية وأقل شبهًا ببث مؤتمت.
  • ملاحظات تفاعلية: في واجهتك الأمامية، اعرض مؤشر "جاري معالجة الصوت..." بعد أن يرسل المستخدم ملفًا صوتيًا لإدارة التوقعات أثناء مرحلة المعالجة السحابية.

🧩 حالات استخدام متقدمة

لافتات إشعارات مدعومة بالصوت

بدلاً من تحديث طلب نصي، أرسل ملاحظة صوتية مدتها 5 ثوانٍ تقول: "مرحبًا! طلبك في الطريق". تزيد اللمسة الشخصية بشكل كبير من التفاعل وولاء العلامة التجارية في الأسواق المحلية.

استجابة صوتية تفاعلية (IVR) لواتساب

قم ببناء بوت دعم حيث يمكن للمستخدمين إرسال ملاحظات صوتية للاستفسارات. يمكن لخلفية تطبيقك تحويل الصوت إلى نص باستخدام خدمة ذكاء اصطناعي، ثم الرد بملاحظة صوتية مسجلة مسبقًا عبر Wawp، مما يخلق واجهة صوتية حوارية حقًا.

🛠️ المزالق الشائعة والحلول

  • أنواع Mime غير متطابقة: تقديم امتداد .mp3 مع نوع mime audio/ogg سيؤدي غالبًا إلى إرجاع المحرك لخطأ Bad Request. تأكد من توافق file[filename] و file[mimetype] مع ملف المصدر الفعلي على خادمك.
  • رؤوس تالفة: تنتج بعض مسجلات الصوت ملفات OGG بأحجام صفحات غير قياسية. إذا وصلت ملاحظة صوتية ولكن لم تعمل، فهذه علامة على تلف الرؤوس. تفعيل convert: true يحل هذا الأمر دائمًا تقريبًا عن طريق إعادة بناء الملف من دفق الصوت الخام.
  • تطبيع مستوى الصوت: يمكن أن تكون الأصوات المؤتمتة صاخبة جدًا أو هادئة جدًا في بعض الأحيان. نوصي بتطبيع مقاطع المصدر الخاصة بك إلى -3dB لضمان مستوى صوت متسق بغض النظر عن إعدادات هاتف المستلم.

ملخص الإمكانيات:

  • تقديم "ملاحظات صوتية" أصلية لواتساب (OGG/Opus) من أي عنوان URL عام (HTTPS).
  • دعم كامل لفك التشفير السحابي من MP3 و AAC و WAV عبر علم convert.
  • تكامل دقيق مع الخيوط والردود باستخدام معلمة reply_to.
  • تقارير نجاح متسقة مع توليد معرف message_id فريد.
  • محسّن للاستهلاك المحمول منخفض النطاق الترددي مع الحفاظ على وضوح صوتي عالٍ.

البارامترات

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

محتوى الطلب

يرسل كـ JSON
string

المعرف الفريد لجلسة واتساب

مثال:
string

رمز وصول API

مثال:
string

معرف واتساب للمستلم (JID). يدعم الأفراد (@c.us)، المجموعات (@g.us)، والقنوات (@newsletter).

مثال:
string

عنوان URL متاح للعامة عبر HTTPS لملف الصوت

مثال:
string

اسم الملف للملاحظة الصوتية

مثال:
string

نوع MIME (يوصى بـ audio/ogg; codecs=opus)

مثال:
boolean

التحويل التلقائي إلى تنسيق OGG/Opus المتوافق مع واتساب

مثال:
string—

معرف الرسالة التي تقوم بالرد عليها

مثال:

أمثلة الكود

استخدم أمثلة الكود الجاهزة لدمج واجهة برمجة التطبيقات (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: 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: طلب غير صالح (تنسيق XML)");
43    }
44    if (response.status === 400) {
45      console.error("Error 400: طلب غير صالح (نص عادي)");
46    }
47    if (response.status === 401) {
48      console.error("Error 401: غير مصرح - مفتاح الوصول غير صالح أو مفقود");
49    }
50    if (response.status === 401) {
51      console.error("Error 401: غير مصرح (تنسيق XML)");
52    }
53    if (response.status === 404) {
54      console.error("Error 404: غير موجود - الجلسة غير موجودة");
55    }
56    if (response.status === 404) {
57      console.error("Error 404: غير موجود (تنسيق XML)");
58    }
59    if (response.status === 429) {
60      console.error("Error 429: طلبات كثيرة جداً - تم تجاوز حد المعدل");
61    }
62    if (response.status === 500) {
63      console.error("Error 500: خطأ في الخادم الداخلي - فشل غير متوقع");
64    }
65    if (response.status === 500) {
66      console.error("Error 500: خطأ في الخادم الداخلي (HTML)");
67    }
68    if (response.status === 502) {
69      console.error("Error 502: بوابة غير صالحة - فشل الاتصال بالخادم الرئيسي");
70    }
71    if (response.status === 502) {
72      console.error("Error 502: بوابة غير صالحة (تنسيق XML)");
73    }
74
75    const errorText = await response.text();
76    console.error(`Error ${response.status}: ${errorText}`);
77  })
78  .catch((error) => console.error("Network Error:", error));
عينات تفاعلية
Ln 78, 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...