What is an image message?
An image message is a WhatsApp message whose content is a single picture with an optional caption: a product photo, a payment QR, a menu, a proof of delivery. On the WhatsApp Cloud API you send one to /{PHONE_NUMBER_ID}/messages with type set to image and an image object that names the file either by id, a Media ID returned by Media Upload, or by link, an HTTPS address WhatsApp fetches when you send. An optional caption adds text under the picture.
The format rules are strict. Images must be JPEG (image/jpeg) or PNG (image/png), 8-bit RGB or RGBA, and no larger than 5 MB. WebP is accepted only in a Sticker Message, and formats such as HEIC from iPhones, GIF or TIFF must be converted before sending. Captions are plain text with a length limit. WhatsApp builds a thumbnail for the chat and may show a recompressed version, so very fine detail can soften on the customer's screen.
An image message is one member of the wider Media Message family, alongside video, audio, documents and stickers, and the full table of types and sizes is on Media File Limits. It is also different from an image in a Template Header: a free-form image message can be sent only inside the 24-hour customer service window, while a template with an image header can start a conversation. In the other direction, a customer's photo reaches your messages webhook as an image object with id, mime_type, sha256 and any caption, and Media Retrieval turns that ID into the file.
Key takeaways
- An image message shows one JPEG or PNG picture of up to 5 MB, with an optional caption, sent with
type: image. - Images must be 8-bit RGB or RGBA; WebP works only as a sticker, and HEIC or GIF files must be converted first.
- Send by uploaded media ID for speed and reuse; a public
linkalso works, but Meta recommends the ID. - A customer's image reaches your webhook as a media ID you can download for 7 days.
- For rate cards, bills and anything with fine print, a PDF document stays sharper than a photo.
Figure 1
Make an image link WhatsApp can fetch
A URL can only carry a small set of characters; everything else travels as %XX bytes.
Try spaces, &, ?, # or ₹.
- Characters in
- 27
- Characters out
- 31
- 2 characters became %XX escapes; letters, digits and - _ . ! ~ * ' ( ) pass through unchanged.
- Spaces became %20. HTML forms use + for a space instead — never mix the two styles.
Example: Product photos at a Jaipur jeweller
A customer asks a Jaipur jeweller, "Do you have this in 22 carat?" From the shared inbox, a sales associate sends three image messages: product photos resized to 1,280-pixel JPEGs of about 300 KB each (illustrative), each captioned with weight, purity and an item code. The customer replies with a screenshot of her favourite; the webhook delivers it as an image ID, and the inbox downloads it straight away and attaches it to the enquiry. The price list itself goes out as a PDF document, because a rate card in a photo can blur once WhatsApp compresses it.
How does an image message work?
Prepare the file
Save photos as JPEG and graphics or screenshots as PNG, 8-bit RGB or RGBA, under 5 MB. Resizing to the size a phone shows and saving at around 80% quality usually lands far below the cap.
Upload it, or host it
Media Upload returns a media ID that lasts 30 days and can be reused for any number of sends. Alternatively host the file at a public URL that returns the right
Content-Type, with every path segment percent-encoded.Send the image message
POST to
/messageswithtype: imageandimage.idorimage.link, plus an optionalcaption. The response carries a WAMID, which means the request was accepted, not that the image was delivered.Watch the status webhooks
sent,deliveredandreadstatuses follow. Afailedstatus with a media error such as 131053 means WhatsApp could not fetch or accept the file, usually a format, size or link problem.Receive customers' images
An inbound image arrives as an ID valid for 7 days. Exchange it for a download URL that works for 5 minutes, fetch it with your access token, check the
sha256and keep your own copy.
An image message in code
curl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/messages" \-H "Authorization: Bearer {ACCESS_TOKEN}" \-H "Content-Type: application/json" \-d '{"messaging_product": "whatsapp","recipient_type": "individual","to": "919812345678","type": "image","image": {"id": "{MEDIA_ID}","caption": "Kundan necklace, 22K, 38.4 g · Item JP-2207"}}'
Upload once with Media Upload, then reuse the same ID for 30 days.
Common mistakes with an image message
Sending HEIC, WebP or GIF as an image
Only JPEG and PNG are accepted. Convert iPhone HEIC photos, WebP exports and GIFs before sending, and check the real type from the file's bytes rather than trusting the extension.
Links WhatsApp cannot fetch
A raw space,
#or Hindi character in the URL, a page behind a login, or a server that answers withtext/htmlbreaks alinksend. Percent-encode each path segment and serve the correctContent-Type, or upload the file and send its ID.Putting fine print in a picture
Rate cards, invoices and terms in an image are hard to read once compressed on a small screen. Send a PDF Document Message, or put the one line that matters in the caption.
Using an image to open a conversation
A free-form image sent after the 24-hour window has closed fails with a re-engagement error. To lead with a picture, use an approved template with an image header.
Downloading customers' images too late
Webhook media IDs expire after 7 days and download URLs after 5 minutes. Fetch inbound images from a queue worker soon after the webhook, then store them yourself.
Why it matters
Why does an image message matter?
Pictures do work that text cannot: the exact saree in stock, a scanned prescription, a damaged-parcel claim, a UPI QR at a shop counter. Getting the format and size right is the difference between an image that arrives instantly and a failed send, and choosing between an image, a Document Message and a template header decides whether the message can go out at all and how readable it is on a small, data-conscious phone.
Best practices for an image message
- Resize to what a chat bubble shows; around 1,000 to 1,600 pixels on the long edge is plenty.
- Put the deciding fact (price, item code, order number) in the caption so it is searchable in the chat.
- Strip EXIF metadata, including location, from photos before sending them to customers.
- Reuse one uploaded media ID for a campaign image instead of uploading it per recipient.
Image Message FAQs
- What is the maximum image size on the WhatsApp Business API?
- 5 MB, for JPEG or PNG images in 8-bit RGB or RGBA. Larger or unsupported files are rejected rather than resized, so compress before sending, or send a PDF document, which allows up to 100 MB.
- Can I send a WebP or GIF image through the WhatsApp API?
- Not as an image message. WebP is accepted only for stickers, and GIF is not a supported image type, so convert to JPEG or PNG, or send motion as an MP4 video. Marketing templates on the Marketing Messages API can use GIF headers, which are MP4 files of up to 3.5 MB.
- Does WhatsApp reduce the quality of images sent through the API?
- It can. WhatsApp generates a thumbnail and may display a recompressed version in the chat, so fine detail can soften. Send a sharp, correctly sized JPEG or PNG, and use a document when every detail must stay legible.
- Should I send images by media ID or by link?
- By media ID where you can. Upload once to get an ID valid for 30 days and reuse it; Meta recommends this for performance. A link makes WhatsApp fetch your URL at send time, so it has to be public, fast and correctly encoded.
- Is an image message charged differently from a text message?
- No. Meta charges per delivered message by category, not by file. An image reply inside an open window is a service message, charged at ₹0.145 in India since 1 October 2026, and an image header on a template is charged at that template's category rate.
* Per-message rates for India, ex-GST: marketing, utility and authentication effective 1 July 2026; service messages ₹0.145 since 1 October 2026 (they were ₹0 until 30 September 2026). Volume commitments earn discounts — final rate is confirmed on your account; applicable GST extra. Rates for other countries differ (see the international rate table on /pricing).