Send Messages

Send Image

SendImage expects a file object (url, mimetype, filename) and required caption/reply_to.

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

Authentication Required

Login to swap the placeholders with your real Instance ID and Access Token.

Log In
Test /v2/send/image endpoint
POSTGET

No query parameters required

This endpoint doesn't expect data in the URL.

Best practices

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

Request Parameters

Configure the parameters required to interact with this endpoint. All query and body arguments are listed below with their details.

Request Body

Sent as a JSON object
string

Unique ID of the WhatsApp session

Example:
string

API access token

Example:
string

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

Example:
string

Publicly accessible HTTPS URL of the image

Example:
string

Filename for the image

Example:
string

MIME type (image/jpeg or image/png)

Example:
string

Caption for the image

Example:
string—

The ID of the message you are replying to

Example:

Request Samples

Use these ready-to-go code snippets to integrate our API into your project quickly and efficiently. Choose your preferred language and library.

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: Bad Request - Missing Required Parameter(s)");
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: Bad Request (XML Format)");
43    }
44    if (response.status === 400) {
45      console.error("Error 400: Bad Request (Plain Text)");
46    }
47    if (response.status === 401) {
48      console.error("Error 401: Unauthorized - Invalid or Missing Access Token");
49    }
50    if (response.status === 401) {
51      console.error("Error 401: Unauthorized (XML Format)");
52    }
53    if (response.status === 404) {
54      console.error("Error 404: Not Found - Session Does Not Exist");
55    }
56    if (response.status === 404) {
57      console.error("Error 404: Not Found (XML Format)");
58    }
59    if (response.status === 429) {
60      console.error("Error 429: Too Many Requests - Rate Limit Exceeded");
61    }
62    if (response.status === 500) {
63      console.error("Error 500: Internal Server Error - Unexpected Failure");
64    }
65    if (response.status === 500) {
66      console.error("Error 500: Internal Server Error (HTML)");
67    }
68    if (response.status === 502) {
69      console.error("Error 502: Bad Gateway - Connection Failed to Upstream");
70    }
71    if (response.status === 502) {
72      console.error("Error 502: Bad Gateway (XML Format)");
73    }
74
75    const errorText = await response.text();
76    console.error(`Error ${response.status}: ${errorText}`);
77  })
78  .catch((error) => console.error("Network Error:", error));
Interactive Samples
Ln 78, Col 1javascript

Expected Responses

Explore all possible responses and outcomes from the server. We have documented each status code with data examples to make success and error handling easier.

Message Sent Successfully
Type:
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": {
  }
}
Bad Request - Missing Required Parameter(s)
Unauthorized - Invalid or Missing Access Token
Not Found - Session Does Not Exist
Too Many Requests - Rate Limit Exceeded
Internal Server Error - Unexpected Failure
Bad Gateway - Connection Failed to Upstream
Previous TopicSend Text Message
Next TopicSend PDF

Command Palette

Search for a command to run...