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

إرسال فيديو

إرسال ملف فيديو إلى دردشة.

POST
https://api.wawp.net/v2/send/video?access_token=123456789&asNote=false&caption=Watch+this+clip&chatId=201234567890%40c.us&convert=true&file%5Bfilename%5D=video.mp4&file%5Bmimetype%5D=video%2Fmp4&file%5Burl%5D=https%3A%2F%2Fwawp.net%2Fsamples%2Ffile_example_MP4_480_1_5MG.mp4&instance_id=123456789

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

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

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

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

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

توصيات

  • أضف تأخيرات عشوائية بين الرسائل لمحاكاة السلوك البشري.

  • تحقق من أرقام الهواتف قبل الإرسال لضمان التسليم.

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

يعد الفيديو الوسيلة المثلى لتقديم المعلومات المعقدة، سواء كان ذلك برنامجًا تعليميًا، أو رسالة شخصية من مدير تنفيذي، أو عرضًا توضيحيًا للمنتج غنيًا بصريًا. تم تصميم نقطة نهاية /v2/send/video للتعامل مع متطلبات البيانات والمعالجة الكبيرة لملفات الفيديو، مما يضمن وصولها إلى هاتف المستلم بتنسيق جاهز للتشغيل الفوري.

🏗️ محرك معالجة الفيديو الذكي

على عكس عمليات نقل الملفات الأساسية، يتعامل Wawp مع مقاطع الفيديو كأصول ديناميكية. يتضمن مسارنا عدة مراحل متخصصة:

  1. التحقق واتساق نوع Mime: يتحقق المحرك من file[mimetype] مقابل الرؤوس الثنائية الفعلية. بينما يعد MP4 هو المعيار، يمكن لمحركنا التعامل مع حاويات مختلفة وتطبيعها لشبكة واتساب.
  2. محرك "التحويل" (Conversion Engine): من أقوى ميزات Wawp هو علم convert. عند تفعيله، يقوم المحرك بتقييم معدل البت والدقة والترميز (H.264/AAC) للفيديو المصدر. إذا كان من المحتمل أن يرفض واتساب الفيديو بسبب معلمات غير متوافقة، يقوم Wawp بإعادة ترميز سحابية لضمان تسليم ناجح.
  3. تخزين الدفق مؤقتًا (Stream Buffering): لمنع فشل الشبكة العابر من إنهاء عملية النقل، يستخدم محركنا استراتيجية تخزين مؤقت تكيفية عند جلب مقاطع الفيديو من file[url] البعيد.

🛡️ أفضل الممارسات الاستراتيجية لتحسين الفيديو

1. حدود الـ 16 ميجابايت

لدى واتساب حد أقصى قدره 16 ميجابايت لعمليات نقل الفيديو على معظم الأجهزة المحمولة.

  • إجراء المطور: إذا كان الفيديو المصدر الخاص بك 50 ميجابايت، فلا ترسله مباشرة. استخدم أداة معالجة مسبقة أو أداة /v2/media/convert الخاصة بنا لجعله أقل من عتبة الـ 16 ميجابايت.
  • معدل البت المستهدف: استهدف معدل بت يتراوح بين 1.5 ميجا بت في الثانية إلى 2 ميجا بت في الثانية بدقة 480p أو 720p. هذا يحقق التوازن المثالي بين الوضوح البصري وسلامة حجم الملف.

2. التنسيق من أجل النجاح (MP4 مقابل غيره)

بينما وجود تنسيقات عديدة، فإن MP4 (H.264) هو المعيار الذهبي لـ Wawp.

  • التشغيل العالمي: من خلال الالتزام بـ H.264، تضمن أن المستخدمين حتى على أجهزة Android أو iOS القديمة يمكنهم تشغيل الفيديو فورًا دون تنزيل برامج ترميز إضافية.
  • مزامنة الصوت: تأكد دائمًا من ترميز الصوت بتنسيق AAC بتردد 44.1 كيلو هرتز أو 48 كيلو هرتز لمنع أخطاء "فيديو بدون صوت" على جهاز المستلم.

3. AsNote: ميزة "ملاحظة الفيديو"

تتيح لك معلمة asNote إرسال مقاطع فيديو بتنسيق "ملاحظة فيديو" دائري مميز.

  • تأثير تجربة المستخدم: تبدو ملاحظات الفيديو الدائرية أكثر شخصية وعفوية. إنها مثالية لرسائل "شكرًا لك" أو تحديثات الحالة السريعة.
  • القيد: تقتصر ملاحظات الفيديو عادةً على 60 ثانية ولا تدعم الشروحات. تأكد من أن محتواك يناسب هذه القيود عند الانتقال إلى وضع "الملاحظة".

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

حملات التدريب بالتنقيط

مقاطع الفيديو مثالية للمحتوى التعليمي اليومي. باستخدام حقل caption، يمكنك تقديم ملخص نصي للنقاط الرئيسية للفيديو. نظرًا لأن Wawp يدعم Markdown بالكامل، يمكنك استخدام رؤوس *عريضة* لجعل الشرح جذابًا مثل الفيديو نفسه.

دعم العملاء عبر لقطات الشاشة المتحركة

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

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

  • فشل الجلب (Failed Fetches): إذا كان خادم الفيديو خلف اتصال بطيء، فقد يتوقف محرك Wawp. تأكد من استجابة مضيف الفيديو الخاص بك لطلبات GET في غضون 5-10 ثوانٍ.
  • مشكلة "لا توجد صورة مصغرة": إذا وصل فيديو ولكن الصورة المصغرة سوداء، فغالباً ما يكون السبب هو أن الإطار الأول من الفيديو أسود. حاول التلاشي للداخل لمحتواك أو التأكد من عدم تلف البيانات الوصفية.
  • برامج ترميز غير مدعومة: محاولة إرسال H.265 (HEVC) أو AV1 دون تعيين convert: true قد يؤدي إلى خطأ "تنسيق غير مدعوم" على الأجهزة القديمة. التزم دائمًا بـ true إذا لم تكن متأكدًا بنسبة 100% من ترميز المصدر.

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

  • تقديم مقاطع فيديو MP4 عالية الجودة مع شروحات غنية بتنسيق Markdown.
  • إعادة ترميز الفيديو سحابيًا تلقائيًا عبر علم convert.
  • دعم تنسيق "ملاحظة الفيديو" الدائري لرسائل عالية التفاعل.
  • الجلب عن بُعد من أي عنوان URL آمن (HTTPS) مع تخزين مؤقت تكيفي.
  • تقارير نجاح متسقة مع توليد معرف message_id فريد لتتبع التسليم الكامل.

البارامترات

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

محتوى الطلب

يرسل كـ JSON
string

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

مثال:
string

رمز وصول API

مثال:
string

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

مثال:
string

الشرح التوضيحي للفيديو

مثال:
boolean

محاولة تحويل الفيديو إلى MP4 متوافق إذا لزم الأمر

مثال:
boolean

الإرسال كـ 'ملاحظة فيديو' دائرية (إذا كان المحرك يدعم ذلك)

مثال:
string

عنوان URL متاح للعامة للفيديو

مثال:
string

اسم الملف للفيديو

مثال:
string

نوع MIME للفيديو

مثال:

أمثلة الكود

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

1const baseUrl = "https://api.wawp.net";
2const endpoint = "/v2/send/video";
3const params = new URLSearchParams({
4  "instance_id": "123456789",
5  "access_token": "123456789"
6}).toString();
7const body = {
8  "chatId": "201234567890@c.us",
9  "caption": "Watch this clip",
10  "convert": "true",
11  "asNote": "false",
12  "file[url]": "https://wawp.net/samples/file_example_MP4_480_1_5MG.mp4",
13  "file[filename]": "video.mp4",
14  "file[mimetype]": "video/mp4"
15};
16
17fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
18  method: "POST",
19  headers: { "Content-Type": "application/json" },
20  body: JSON.stringify(body)
21})
22  .then(async (response) => {
23    if (response.ok) {
24      const data = await response.json();
25      console.log("Success:", data);
26      return data;
27    }
28    
29    // Error Handling
30    if (response.status === 400) {
31      console.error("Error 400: طلب غير صالح - معاملات مطلوبة مفقودة");
32    }
33    if (response.status === 400) {
34      console.error("Error 400: Bad Request - Invalid Number (Egypt)");
35    }
36    if (response.status === 400) {
37      console.error("Error 400: Bad Request - Invalid Number (Saudi Arabia)");
38    }
39    if (response.status === 400) {
40      console.error("Error 400: Bad Request - Invalid Number (Unknown)");
41    }
42    if (response.status === 400) {
43      console.error("Error 400: طلب غير صالح (تنسيق XML)");
44    }
45    if (response.status === 400) {
46      console.error("Error 400: طلب غير صالح (نص عادي)");
47    }
48    if (response.status === 401) {
49      console.error("Error 401: غير مصرح - مفتاح الوصول غير صالح أو مفقود");
50    }
51    if (response.status === 401) {
52      console.error("Error 401: غير مصرح (تنسيق XML)");
53    }
54    if (response.status === 404) {
55      console.error("Error 404: غير موجود - الجلسة غير موجودة");
56    }
57    if (response.status === 404) {
58      console.error("Error 404: غير موجود (تنسيق XML)");
59    }
60    if (response.status === 429) {
61      console.error("Error 429: طلبات كثيرة جداً - تم تجاوز حد المعدل");
62    }
63    if (response.status === 500) {
64      console.error("Error 500: خطأ في الخادم الداخلي - فشل غير متوقع");
65    }
66    if (response.status === 500) {
67      console.error("Error 500: خطأ في الخادم الداخلي (HTML)");
68    }
69    if (response.status === 502) {
70      console.error("Error 502: بوابة غير صالحة - فشل الاتصال بالخادم الرئيسي");
71    }
72    if (response.status === 502) {
73      console.error("Error 502: بوابة غير صالحة (تنسيق XML)");
74    }
75
76    const errorText = await response.text();
77    console.error(`Error ${response.status}: ${errorText}`);
78  })
79  .catch((error) => console.error("Network Error:", error));
عينات تفاعلية
Ln 79, 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": {
  }
}
طلب غير صالح - معاملات مطلوبة مفقودة
غير مصرح - مفتاح الوصول غير صالح أو مفقود
غير موجود - الجلسة غير موجودة
طلبات كثيرة جداً - تم تجاوز حد المعدل
خطأ في الخادم الداخلي - فشل غير متوقع
بوابة غير صالحة - فشل الاتصال بالخادم الرئيسي
الموضوع السابقإرسال رسالة صوتية
الموضوع التاليإرسال رابط معاينة (Link Preview)

Command Palette

Search for a command to run...