Skip to main content
An image message sends a single image (JPEG or PNG) to a recipient, with an optional caption displayed below the photo. The image can be provided as a public URL or as a media ID from a prior upload. See Media by URL vs Media ID for when to use each.

​
Send by URL

{
  "messaging_product": "whatsapp",
  "to": "919959623255",
  "type": "image",
  "image": {
    "link": "https://www.luckyshrub.com/assets/succulents/aloe.png",
    "caption": "Here is your product photo!"
  }
}

​
Send by Media ID

{
  "messaging_product": "whatsapp",
  "to": "919959623255",
  "type": "image",
  "image": {
    "id": "1234567890",
    "caption": "Here is your product photo!"
  }
}

​
Supported formats

FormatMIME typeExtensionMax size
JPEGimage/jpeg.jpeg / .jpg5 MB
PNGimage/png.png5 MB
  • Images must be 8-bit RGB or RGBA.
  • Files larger than 5 MB will be rejected by the API.
  • Other formats (GIF, WebP, BMP, HEIC) are not supported — convert them to JPEG or PNG before sending.

​
Caption

The caption field is optional. It appears as plain text below the image. Max 1024 characters. Leave it out if you only want to send the image.

​
Reference image

Image message example

​
Frequently asked

Set type to "image" in your request body and include either a public https:// URL in image.link or a previously uploaded media ID in image.id. Optionally add image.caption for text below the photo.
JPEG and PNG only, max 5 MB each. The image must be 8-bit RGB or RGBA. If you have a different format, convert it to JPEG or PNG first.
Check three things: (1) the file is JPEG or PNG and under 5 MB, (2) if using a URL it is public https:// with no authentication required, (3) the 24-hour customer service window is open if sending free-form messages. See The 24-hour window and Media by URL vs Media ID.
Yes — use the caption field in the image object. It accepts plain text up to 1024 characters and appears below the photo in the chat.
No. GIF is not a supported image type. Convert it to JPEG or PNG, or use a video message for animated content.

​
Gotchas & common mistakes

  • Wrong format — only JPEG and PNG are accepted. WebP, GIF, BMP, and HEIC will fail.
  • File over 5 MB — compress or resize the image before sending. The API rejects larger files without a helpful error message.
  • http:// URL — must be https://. Plain HTTP URLs are rejected.
  • Private URL — the URL must be publicly accessible. If it requires a login or is on localhost, use the media ID method instead.
  • Caption too long — max 1024 characters.