Image Messages

Image messages allow you to send images to your recipients through WhatsApp. You can send images using either a URL or a previously uploaded Media ID.

Basic Usage

import WhatsApp from 'meta-cloud-api';

// Initialize client
const whatsapp = new WhatsApp({
  phoneNumberId: YOUR_PHONE_NUMBER_ID,
  accessToken: 'YOUR_ACCESS_TOKEN'
});

// Send image message using a URL
const response = await whatsapp.messages.image({
  body: { 
    link: "https://example.com/image.jpg",
    caption: "Check out this image!"
  },
  to: "15551234567"
});

console.log(`Image message sent with ID: ${response.messages[0].id}`);

Parameters

The image() method accepts the following parameters:

Parameter	Type	Description
params	MessageRequestParamsImageMediaObject	Object containing message parameters

MessageRequestParamsImageMediaObject Properties

Property	Type	Description	Required
body	ImageMediaObject	The image message body	Required
to	string	The recipient's phone number with country code	Required
replyMessageId	string	ID of a message to reply to	Optional

ImageMediaObject Properties

Property	Type	Description	Required
link	string	URL of the image	Required if id is not provided
id	string	Media ID of a previously uploaded image	Required if link is not provided
caption	string	Text caption for the image	Optional

Examples

Sending an Image with a URL

const response = await whatsapp.messages.image({
  body: { 
    link: "https://example.com/product.jpg",
    caption: "Our new product"
  },
  to: "15551234567"
});

Sending an Image with a Media ID

If you've previously uploaded an image and have its Media ID:

const response = await whatsapp.messages.image({
  body: { 
    id: "1234567890",
    caption: "Image from our media library"
  },
  to: "15551234567"
});

Sending an Image without Caption

const response = await whatsapp.messages.image({
  body: { 
    link: "https://example.com/infographic.jpg"
  },
  to: "15551234567"
});

Replying with an Image

const originalMessageId = "wamid.abcd1234...";

const response = await whatsapp.messages.image({
  body: { 
    link: "https://example.com/response-image.jpg",
    caption: "Here's the image you requested"
  },
  to: "15551234567",
  replyMessageId: originalMessageId
});

Uploading Images

Before sending images with a Media ID, you need to upload them:

// Upload an image file
const uploadResponse = await whatsapp.media.upload({
  file: "/path/to/local/image.jpg",
  type: "image/jpeg"
});

// Get the media ID from the response
const mediaId = uploadResponse.id;

// Now send the image using the media ID
const messageResponse = await whatsapp.messages.image({
  body: { 
    id: mediaId,
    caption: "Image uploaded and sent"
  },
  to: "15551234567"
});

Supported Formats and Limits

• Supported formats: JPEG, PNG
• Maximum file size: 5 MB
• Image requirements: 8-bit, RGB or RGBA

Error Handling

try {
  const response = await whatsapp.messages.image({
    body: { 
      link: "https://example.com/image.jpg",
      caption: "Check out this image!"
    },
    to: "15551234567"
  });
  console.log("Image message sent successfully:", response);
} catch (error) {
  console.error("Error sending image message:", error);
  
  // Handle specific error cases
  if (error.response && error.response.data) {
    if (error.response.data.error.code === 131053) {
      console.log("Media URL is not accessible or supported");
    } else {
      console.log("Error details:", error.response.data);
    }
  }
}

Best Practices

1. Optimize image size: Keep images under 5 MB and optimize them for mobile viewing.

2. Use descriptive captions: Add context to your images with clear captions.

3. Host images reliably: Ensure your image URLs are from reliable, high-uptime hosts.

4. Consider bandwidth: Be mindful of users who may have limited data plans.

5. Accessibility: When possible, include descriptive captions that explain the image content for visually impaired users.

Related

• Media API - For uploading and managing media
• Document Messages - For sending documents
• Video Messages - For sending videos