WhatsApp API Media: Supported File Types and Size Limits

Should I upload media or send a link?

Meta recommends uploading the file and sending its media ID. You can alternatively send a link to a file on a public server, but Meta's image, video and document references say to prefer the uploaded ID for better performance, and its throughput guidance says the same for higher volumes.

With Meta's own endpoint, an upload is a POST to /<PHONE_NUMBER_ID>/media with the file, its MIME type and messaging_product=whatsapp, and the response is {"id": "<MEDIA_ID>"}. Uploaded files are encrypted and kept for 30 days unless you delete them first.

On the OmniChannels.ai WhatsApp endpoint, a media message takes either mediaUrl (a public HTTPS URL) or mediaFile (a file you upload with the request), with the caption in content. See the WhatsApp API docs. Ask our team how your account handles media storage and reuse for large sends.

How long do media IDs stay valid?

Meta documents 30 days for an ID returned by an upload and 7 days for an ID received in an inbound webhook. The download URL returned for an ID expires after 5 minutes.

Practical consequences:

• Do not cache a media ID for months. Store your original file and re-upload when an ID is rejected.
• Download inbound files as soon as the event arrives and keep your own copy.
• Never store a retrieved download URL; ask for a new one when you need it.

Can I add captions to media messages?

Yes. Image, video and document messages accept an optional caption of up to 1,024 characters, per Meta's message references. Captions are plain text next to the file.

Audio and sticker messages have no caption in this model. If you need words with a voice note, send a short text message beside it. Captions inside the customer service window are free-form; outside it, media must travel inside an approved template.

How does media work in message templates?

A template can have an image, video or document in its header, and that header is fixed when you create the template. When you submit a template for approval you provide a sample file, and you can supply the actual file when you send.

On our API, headerFormat can be IMAGE, VIDEO or DOCUMENT at creation, headerFile carries the sample, and mediaUrl at send time overrides the header media. Check Meta's template documentation for sample-file requirements. See template categories and approval and template examples.

How do I download media a customer sends?

Inbound media arrives as a webhook with a media ID; you resolve it to a URL and download it with authorisation.

1. Read the media ID from the inbound message event.
2. Request the media URL for that ID. Meta's response includes url, mime_type, sha256 and file_size.
3. Send a GET to that URL with an Authorization: Bearer <token> header. Without the token the request fails.
4. Check the Content-Type header and the sha256 value, then store the file.
5. On a 404, request a new URL and retry; if that still fails, renew the access token.

Meta's maximum inbound media size on the Cloud API is 100 MB. A larger file triggers a webhook with error code 131052; ask the customer to send a smaller file or share it another way. Scan every file before opening it internally. See the webhooks guide, and confirm with your onboarding engineer how inbound media is delivered on your account.

Worked example: a dental clinic sending reports

"Nile Smile Clinic" (synthetic) in Cairo sends appointment cards and X-ray reports.

1. Appointment cards are 300 KB PNG images with a caption of two lines. Well under 5 MB.
2. Treatment reports are PDFs of 2 to 8 MB, named report-2026-0381.pdf, sent as documents.
3. A 25 MB clinic tour video is too large for video. The team re-encodes it as H.264/AAC MP4 at under 16 MB with faststart.
4. Patients send photos of prescriptions. The inbox downloads each file immediately, because the inbound ID expires after 7 days.
5. A voice greeting is exported as mono Opus OGG, since other OGG variants are rejected.

What are the common mistakes?

• Judging by size alone. A 3 MB image in the wrong colour format or a video with the wrong codec still fails.
• MIME mismatch. A .jpg served as application/octet-stream is a classic cause of error 131053.
• Linking to a slow or private URL, such as a signed link that has expired or a page behind a login.
• Relying on an old media ID. IDs expire after 30 days.
• Ignoring inbound expiry. Customer files must be saved within 7 days.
• Animated WebP as an image. It is rejected; use a sticker or a video.
• Limits change. Re-check Meta's reference before you hard-code validation.

How OmniChannels.ai helps

OmniChannels.ai sends WhatsApp image, video, audio, document and sticker messages through one API, with a public link or an uploaded file and a caption, and shows media and attachments in the shared inbox. BroadNet is an official Meta Business Solution Provider, so templates with image, video or document headers can be created and tracked with approval status. Read the WhatsApp API docs and errors and limits, or see the WhatsApp channel.