Supported Media Types

Reference guide for all media formats supported by the WhatsApp Business API, including file size limits, format requirements, and best practices for media delivery.

Media Type Reference

The following table lists every media type supported by the WhatsApp Business API, along with accepted formats and size constraints.

Type	Supported Formats	Max Size	Notes
Image	JPEG, PNG	5 MB	Must be 8-bit, RGB or RGBA color space. Animated GIFs are not supported as images.
Video	MP4, 3GPP	16 MB	H.264 video codec and AAC audio codec required. Only MP4 with H.264 is broadly supported.
Audio	AAC, MP4, MPEG, AMR, OGG (Opus codecs only)	16 MB	Captions are not supported for audio messages. OGG files must use Opus codec.
Document	PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX, TXT	100 MB	Always include the filename parameter with the correct file extension for proper display.
Sticker (static)	WebP	100 KB	Must be exactly 512 × 512 pixels with a transparent background.
Sticker (animated)	WebP	500 KB	Must be exactly 512 × 512 pixels with a transparent background.

Media URL Requirements

When sending media via URL, the WhatsApp servers download the file from the provided link. Your URLs must meet the following requirements:

• Publicly accessible — the URL must be reachable without authentication. WhatsApp servers cannot pass credentials or cookies when fetching media.
• HTTPS recommended — while HTTP URLs may work, HTTPS is strongly recommended for security and reliability.
• Correct Content-Type headers — the server hosting the media must return the proper Content-Type header (e.g., image/jpeg, application/pdf) for WhatsApp to process the file correctly.
• No authentication required — do not use signed URLs that expire before WhatsApp can download the file. Ensure URLs remain valid for at least several minutes after sending.
• Cached for 7 days — WhatsApp caches downloaded media for up to 7 days. If you update a file at the same URL, it may not reflect immediately for recipients.

Sending Media Messages

To send a media message, include the media URL and type in your API request. Below are examples for the most common media types.

Image Message

Document Message

Video Message

Audio Message

Media Parameters

Parameter	Type	Description
type required	string	The media type. One of: image, video, audio, document, sticker.
media_url required	string	A publicly accessible URL pointing to the media file. Must return the correct Content-Type header.
caption optional	string	Caption text displayed below the media. Supported for image, video, and document types. Not supported for audio or sticker.
filename optional	string	The filename displayed to the recipient. Required for documents to ensure the correct file extension is shown (e.g., report.pdf).

Tips & Best Practices

• Use CDN-hosted URLs for faster and more reliable media delivery. Content delivery networks reduce latency and improve download speeds for WhatsApp servers.
• Compress images before sending to improve delivery speed and reduce bandwidth usage. Tools like TinyPNG or ImageOptim can reduce file size without visible quality loss.
• Always include the filename parameter for documents with the correct file extension (e.g., invoice.pdf, report.xlsx). Without it, recipients may see a generic filename.
• Validate file sizes client-side before making API calls. Rejections for oversized files count against your rate limit.
• Test media on multiple devices. While WhatsApp handles most rendering, edge cases in video codecs or image color profiles may display differently across iOS and Android.

Common Media Errors

Error	Cause	Solution
Media download failed	URL is not publicly accessible or has expired.	Ensure the URL is accessible without authentication and has a long expiration time.
Unsupported media type	File format is not in the supported list.	Convert the file to a supported format before sending (e.g., convert BMP to JPEG).
File too large	File exceeds the maximum size for its media type.	Compress or resize the file to meet the size limit shown in the reference table above.
Invalid Content-Type	The hosting server returns an incorrect or missing Content-Type header.	Configure your server or CDN to return the correct MIME type for the file.