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

إرسال صورة عبر الواتساب

إرسال ملفات الصور الرسومية عبر الـ API مع تسمية توضيحية.

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

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

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

توصيات

  • Use "reply_to" to maintain conversation context.

  • Handle distinct message types (text, image, video) appropriately.

  • Implement a robust retry mechanism for failed sends.

Visual Storytelling: Harnessing the Image Messaging Engine

Images are the most engaging form of communication on WhatsApp. Whether it's a product catalog, a promotional banner, or a technical screenshot, the /v2/send/image endpoint provides a robust way to deliver high-quality visuals to your users. Wawp’s image engine handles the heavy lifting of fetching remote assets, validating MIME types, and ensuring that images are rendered correctly on all WhatsApp clients (Mobile, Web, and Desktop).

🏗️ The Multi-Stage Media Pipeline

When you call the /send/image endpoint, Wawp orchestrates a complex background process:

  1. Asynchronous Fetching: The engine uses a high-speed fetcher to retrieve the file from the providing URL. We recommend using a Content Delivery Network (CDN) to ensure low-latency transfers.
  2. Format Verification: WhatsApp is strict about image standards. Our engine verifies that the file is a valid PNG or JPEG. If the upstream server provides a different format (like WebP or SVG via a mismatched extension), Wawp attempts to normalize the stream or returns an informative error code.
  3. Caption Injection: Unlike simple attachments, captions in Wawp are treated as first-class text citizens. They support full UTF-8 encoding and WhatsApp markdown (*bold*, etc.), allowing you to provide context directly alongside the visual.

🛡️ Strategic Best Practices for Media Delivery

1. The Pre-fetch Metadata Pattern

To provide the best user experience, your application should know what it's sending before it hits our API.

  • Validation: Before calling the API, perform a HEAD request to the image URL to verify the Content-Length and Content-Type. This prevents "Blind Sending" which leads to higher failure rates.
  • Client-Side Thumbs: In your frontend, render a local thumbnail of the image. This gives the user immediate visual feedback while our engine handles the upstream delivery.

2. File Size and Resolution Strategy

While WhatsApp supports large files, efficiency is key to engagement.

  • Optimal Resolution: Aim for 1200x1600 pixels. This provides a sharp, full-screen experience on most mobile devices without excessive bandwidth consumption.
  • Compression: Leverage our /v2/media/convert endpoint if you need to downscale or compress high-resolution photography before sending it to a mass audience.

3. URL Accessibility and Security

  • Public Accessibility: The file[url] must be publicly accessible via HTTPS. Our engine cannot bypass login screens or VPN-locked assets.
  • Expiring Links: If you use signed S3 URLs, ensure the expiration time is at least 5 minutes. This gives the Wawp engine enough time to fetch and process the file even during peak traffic periods.

🧩 Advanced Use Cases

Catalog Branding

Images are perfect for sending product highlights. Pair the image with a long, descriptive caption that includes a CTA (Call to Action) link. Since the caption remains attached to the image upon forwarding, your branding stays intact.

Technical Support via Visuals

Use images to send "Before/After" comparisons or flow diagrams. By using the reply_to field, you can link an instruction image directly to a user's specific query, creating a seamless support thread.

🛠️ Common Pitfalls and Solutions

  • Invalid Mime-Types: Sending a .jpg file with an image/gif header is a common technical error. Wawp will return an Unsupported Mimetype error. Always ensure your server headers are correct.
  • Filename Ambiguity: Use descriptive but clean filenames (e.g., invoice_123.jpg). Avoid using special characters or spaces in the file[filename] parameter to ensure compatibility across different OS file systems.
  • The "Broken Thumbnail" Issue: If an image appears as a grey box on the recipient's phone, it usually means the source URL was cut off mid-download or the server returned a 404/500 code during Wawp's fetch phase.

Summary of Capabilities:

  • Deliver high-fidelity JPEG and PNG images with integrated captions.
  • Remote fetching from any secure HTTPS URL.
  • Support for complex thread-nesting via the reply_to parameter.
  • Reliable MIME-type validation and header normalization.
  • Consistent success reporting with unique message_id generation for delivery tracking.

البارامترات

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

محتوى الطلب

يرسل كـ 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 image

مثال:
string

Filename for the image

مثال:
string

MIME type (image/jpeg or image/png)

مثال:
string

Caption for the image

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

Command Palette

Search for a command to run...