WhatsApp Business API media message

How to send media messages via WhatsApp Business API, including upload and headers.

Media messages in WhatsApp Business API support images, documents, audio, and video. Upload media to get an ID, then reference it in your send payload.

Key takeaways

Upload media first to receive a media ID.
Use the correct type field (image/document/audio/video/sticker).
Ensure media is hosted/accessible per policy and size limits.

Sending media

Upload media via the media endpoint and store the returned ID.
Send with type set to the media type and include the media ID.
Optionally add caption fields where supported (image/video/document).

Best practices

Keep media lightweight and relevant to reduce delivery issues.
Avoid sensitive content; follow WhatsApp media policies.
Handle upload errors and retries gracefully.

Example payload

{ "messaging_product": "whatsapp", "to": "<PHONE>", "type": "image", "image": { "id": "<MEDIA_ID>", "caption": "Thanks for your order!" } }

FAQs

Can I send media via URL?

Cloud API supports both IDs and URLs in some cases, but uploading and using IDs is more reliable.

What are the size limits?

Limits vary by type (e.g., images up to a few MB). Check current provider/Meta limits.

Do media messages cost extra?

Meta charges per conversation, not per media type. Providers may bill for storage/bandwidth.

Try BotMax AI

Launch WhatsApp automation with compliant messaging

Verified templates, inbox for teams, broadcasts, reminders, and billing workflows.

Talk to sales Start a trial