Skip to main content
Send an image message to a WhatsApp number or group. Supports image upload, URL-based images, captions, compression, and view-once mode.
Images can be sent either by uploading a file or providing a URL. The API supports compression and view-once ephemeral images.

​
Endpoint

POST /send/image

​
Headers

​
X-Device-Id
string
Device identifier for multi-device support. Required when multiple devices are registered.
​
Content-Type
string
required
Must be multipart/form-data for file uploads.

​
Request Body (multipart/form-data)

​
phone
string
required
Phone number with country code and WhatsApp suffix.Format: {country_code}{phone_number}@s.whatsapp.netExample: [email protected]
​
caption
string
Optional caption text for the image. Supports up to 3000 characters.Example: "Beautiful sunset at the beach"
​
image
file
Image file to upload. Supports common image formats (JPEG, PNG, GIF, WebP).
Either image (file upload) or image_url must be provided, but not both.
​
image_url
string
URL of the image to send. The API will download and send the image from this URL.Example: "https://example.com/image.jpg"
Either image (file upload) or image_url must be provided, but not both.
​
view_once
boolean
default:false
Enable view-once mode. When enabled, the image can only be viewed once by the recipient and will disappear after being opened.
View-once images cannot be forwarded, saved, or screenshot without notification (on supported devices).
​
compress
boolean
default:false
Compress the image before sending to reduce file size and improve delivery speed. Useful for large images.
​
duration
integer
Disappearing message duration in seconds.Common values:
  • 86400 - 24 hours
  • 604800 - 7 days
  • 7776000 - 90 days
​
is_forwarded
boolean
default:false
Mark the message as forwarded.

​
Response

​
code
string
Response status code. Returns "SUCCESS" on successful send.
​
message
string
Human-readable response message.
​
results
object
​
message_id
string
Unique identifier for the sent message.Example: "3EB0B430B6F8F1D0E053AC120E0A9E5C"
​
status
string
Detailed status message.

​
Code Examples

curl -X POST http://localhost:3000/send/image \
  -H "X-Device-Id: my-device" \
  -F "[email protected]" \
  -F "caption=Check out this amazing photo!" \
  -F "image=@/path/to/image.jpg"

​
Response Example

{
  "code": "SUCCESS",
  "message": "Success",
  "results": {
    "message_id": "3EB0B430B6F8F1D0E053AC120E0A9E5C",
    "status": "Image sent successfully"
  }
}

​
Features

​
View Once Images

View-once images provide enhanced privacy by allowing recipients to view the image only once: 
curl -X POST http://localhost:3000/send/image \
  -H "X-Device-Id: my-device" \
  -F "[email protected]" \
  -F "image=@/path/to/private.jpg" \
  -F "view_once=true"
Once opened, the image disappears and cannot be viewed again. The sender is notified when the recipient opens the image.

​
Image Compression

Enable compression to reduce file size while maintaining acceptable quality: 
curl -X POST http://localhost:3000/send/image \
  -H "X-Device-Id: my-device" \
  -F "[email protected]" \
  -F "image=@/path/to/10mb-image.jpg" \
  -F "compress=true"
Compression is particularly useful for:
  • Large image files (>5MB)
  • Reducing bandwidth usage
  • Faster delivery times
  • Recipients with slower connections

​
URL-Based Image Sending

Send images directly from URLs without downloading them first: 
curl -X POST http://localhost:3000/send/image \
  -H "X-Device-Id: my-device" \
  -F "[email protected]" \
  -F "image_url=https://cdn.example.com/products/item-123.jpg" \
  -F "caption=Product Image"
This is useful for:
  • E-commerce integrations
  • Content management systems
  • Automated image sharing from cloud storage

​
Image Requirements

​
Supported Formats

  • JPEG (.jpg, .jpeg)
  • PNG (.png)
  • GIF (.gif)
  • WebP (.webp)

​
File Size Limits

  • Maximum file size: 16MB (uncompressed)
  • Recommended: Under 5MB for optimal delivery
  • Use compression for larger files

​
Image Dimensions

  • Minimum: 48x48 pixels
  • Maximum: 16000x16000 pixels
  • Recommended aspect ratio: 4:5 or 1:1 for best display

​
Best Practices

  1. Choose the Right Method: Use file upload for local images, URL method for images already hosted online.
  2. Optimize Before Upload: Pre-optimize images before sending to reduce processing time and bandwidth.
  3. Use Compression Wisely: Enable compression for large files, but avoid it for images that need to preserve quality (screenshots, text images).
  4. Caption Length: Keep captions concise. While WhatsApp supports up to 3000 characters, shorter captions provide better UX.
  5. View Once for Sensitive Content: Use view-once mode for confidential or time-sensitive images.
  6. Error Handling: Implement retry logic for failed uploads, especially when using URL-based sending.

​
Error Responses

​
400
Bad Request
Common causes:
  • Invalid phone number format
  • Missing both image and image_url
  • Providing both image and image_url
  • Invalid image format
  • File too large
​
500
Internal Server Error
Common causes:
  • Device not connected
  • Failed to download image from URL
  • Image processing error
  • Network connectivity issues

Build docs developers (and LLMs) love

Get started for freeTalk to us