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

إرسال صورة

تتوقع SendImage كائن ملف (url، mimetype، filename) وشرح/رد مطلوب.

POST
https://api.wawp.net/v2/send/image?access_token=YOUR_ACCESS_TOKEN&caption=Here%27s+your+requested+image.&chatId=201234567890%40c.us&file%5Bfilename%5D=image.jpg&file%5Bmimetype%5D=image%2Fjpeg&file%5Burl%5D=https%3A%2F%2Fwawp.net%2Fsamples%2Fcat.jpg&instance_id=123456789&reply_to=false_111...AAAA

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

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

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

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

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

توصيات

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

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

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

الصور هي أكثر أشكال التواصل جاذبية على واتساب. سواء كان ذلك كتالوج منتجات، أو بنر ترويجي، أو لقطة شاشة تقنية، فإن نقطة النهاية /v2/send/image توفر طريقة قوية لتقديم مرئيات عالية الجودة لمستخدميك. يتعامل محرك صور Wawp مع الأعباء الثقيلة لجلب الأصول عن بُعد، والتحقق من أنواع MIME، وضمان عرض الصور بشكل صحيح على جميع عملاء واتساب (الجوال، الويب، وسطح المكتب).

إرسال صورة

🏗️ مسار الوسائط متعدد المراحل

عندما تستدعي نقطة النهاية /send/image، ينظم Wawp عملية خلفية معقدة:

  1. الجلب غير المتزامن (Asynchronous Fetching): يستخدم المحرك جالبًا عالي السرعة لاسترداد الملف من عنوان URL المقدم. نوصي باستخدام شبكة توصيل المحتوى (CDN) لضمان عمليات نقل منخفضة التأخير.
  2. التحقق من التنسيق: واتساب صارم بشأن معايير الصور. يتحقق محركنا من أن الملف هو PNG أو JPEG صالح. إذا قدم الخادم المصدر تنسيقًا مختلفًا (مثل WebP أو SVG عبر امتداد غير متطابق)، يحاول Wawp تطبيع الدفق أو يرجع رمز خطأ مفيدًا.
  3. حقن الشرح (Caption Injection): على عكس المرفقات البسيطة، يتم التعامل مع الشروحات في Wawp كمواطنين نصيين من الدرجة الأولى. وهي تدعم ترميز UTF-8 الكامل وتنسيق Markdown الخاص بواتساب (*bold* إلخ)، مما يتيح لك تقديم سياق مباشر بجانب المرئيات.

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

1. نمط البيانات المسبقة (Pre-fetch Metadata Pattern)

لتقديم أفضل تجربة مستخدم، يجب أن يعرف تطبيقك ما يرسله قبل أن يصل إلى واجهة البرمجة الخاصة بنا.

  • التحقق: قبل استدعاء API، قم بإجراء طلب HEAD لعنوان URL للصورة للتحقق من Content-Length و Content-Type. هذا يمنع "الإرسال الأعمى" الذي يؤدي إلى معدلات فشل أعلى.
  • الصور المصغرة من جانب العميل: في واجهتك الأمامية، قم بعرض صورة مصغرة محلية للصورة. يعطي هذا المستخدم ملاحظات مرئية فورية بينما يتعامل محركنا مع التسليم الأصلي.

2. استراتيجية حجم الملف والدقة

بينما يدعم واتساب الملفات الكبيرة، فإن الكفاءة هي مفتاح التفاعل.

  • الدقة المثالية: استهدف 1200x1600 بكسل. يوفر هذا تجربة حادة بملء الشاشة على معظم الأجهزة المحمولة دون استهلاك مفرط للنطاق الترددي.
  • الضغط: استفد من نقطة النهاية /v2/media/convert الخاصة بنا إذا كنت بحاجة إلى تقليل حجم الصور عالية الدقة أو ضغطها قبل إرسالها إلى جمهور كبير.

3. سهولة الوصول إلى URL والأمان

  • الوصول العام: يجب أن يكون file[url] متاحًا علنًا عبر HTTPS. لا يمكن لمحركنا تجاوز شاشات تسجيل الدخول أو الأصول المقفولة بـ VPN.
  • الروابط منتهية الصلاحية: إذا كنت تستخدم روابط S3 الموقعة، فتأكد من أن وقت انتهاء الصلاحية لا يقل عن 5 دقائق. يمنح هذا محرك Wawp وقتًا كافيًا لجلب الملف ومعالجته حتى في فترات ذروة الحركة.

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

هوية الكتالوج

الصور مثالية لإرسال أبرز ميزات المنتج. اربط الصورة بشرح وصفي طويل يتضمن رابطًا لاتخاذ إجراء (CTA). نظرًا لأن الشرح يظل مرفقًا بالصورة عند إعادة التوجيه، فإن هويتك تظل سليمة.

الدعم الفني عبر المرئيات

استخدم الصور لإرسال مقارنات "قبل/بعد" أو مخططات التدفق. باستخدام حقل reply_to، يمكنك ربط صورة تعليمية مباشرة باستفسار محدد للمستخدم، مما يؤدي إلى إنشاء خيط دعم سلس.

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

  • أنواع Mime غير صالحة: إرسال ملف .jpg مع رأس image/gif هو خطأ تقني شائع. سيعيد Wawp خطأ Unsupported Mimetype. تأكد دائمًا من صحة رؤوس الخادم الخاص بك.
  • غموض اسم الملف: استخدم أسماء ملفات وصفية ولكن نظيفة (مثلاً invoice_123.jpg). تجنب استخدام رموز خاصة أو مسافات في معلمة file[filename] لضمان التوافق عبر أنظمة تشغيل الملفات المختلفة.
  • مشكلة "الصورة المصغرة المعطلة": إذا ظهرت الصورة كمربع رمادي على هاتف المستلم، فهذا يعني عادةً أن عنوان URL المصدر قد انقطع في منتصف التنزيل أو أن الخادم أرجع رمز 404/500 أثناء مرحلة جلب Wawp.

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

  • تقديم صور JPEG و PNG عالية الدقة مع شروحات متكاملة.
  • الجلب عن بُعد من أي عنوان URL آمن (HTTPS).
  • دعم لتداخل الخيوط المعقدة عبر معلمة reply_to.
  • تحقق موثوق من نوع MIME وتطبيع الرؤوس.
  • تقارير نجاح متسقة مع توليد معرف message_id فريد لتتبع التسليم.

البارامترات

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

محتوى الطلب

يرسل كـ JSON
string

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

مثال:
string

رمز وصول API

مثال:
string

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

مثال:
string

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

مثال:
string

اسم الملف للصورة

مثال:
string

نوع MIME (image/jpeg أو image/png)

مثال:
string

الشرح التوضيحي للصورة

مثال:
string—

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

مثال:

أمثلة الكود

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

1const baseUrl = "https://api.wawp.net";
2const endpoint = "/v2/send/image";
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://wawp.net/samples/cat.jpg",
10  "file[filename]": "image.jpg",
11  "file[mimetype]": "image/jpeg",
12  "caption": "Here's your requested image.",
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": {
  }
}
طلب غير صالح - معاملات مطلوبة مفقودة
غير مصرح - مفتاح الوصول غير صالح أو مفقود
غير موجود - الجلسة غير موجودة
طلبات كثيرة جداً - تم تجاوز حد المعدل
خطأ في الخادم الداخلي - فشل غير متوقع
بوابة غير صالحة - فشل الاتصال بالخادم الرئيسي
الموضوع السابقإرسال رسالة نصية
الموضوع التاليإرسال ملف PDF

Command Palette

Search for a command to run...