WhatsApp API media messages: file types, size limits and how to send a PDF to customers

Kavitha Nair runs a nine-person team at a silk and gold boutique in Thrissur. Her wedding-season price list is a 14 MB PDF with photographs, her product videos are shot on a phone in portrait, and the owner likes to send a voice note in Malayalam to regular customers. The question she sent her provider was simple: which of these can go out through the WhatsApp Business Platform, and what happens to the file afterwards? Kavitha is invented; the file sizes are the ones we see every week.

All of it can be sent. Meta’s Cloud API carries text, images, video, audio and voice notes, documents, stickers, locations, contact cards, emoji reactions and quoted replies, along with the buttons and lists covered in our buttons and list messages guide. What follows is the file rules Meta publishes for each type, including the WhatsApp API image size limit, how media is uploaded and how briefly Meta keeps it, what customers can send you, and the practical choices for an Indian business. Terms are defined in our glossary.

What can a business send on WhatsApp through the Cloud API?

Ten content types, each with its own file rules. Meta’s media page, updated 16 June 2026, and the message-type pages give these limits:

Type	Formats	Size cap	Caption	Notes
Text	Plain text	4,096 characters	n/a	Preview of the first URL if enabled
Image	JPEG, PNG; 8-bit, RGB or RGBA	5 MB	Up to 1,024 characters	WebP does not count as an image
Video	MP4, 3GPP; H.264 video, AAC audio	16 MB	Up to 1,024 characters	Single audio stream or none
Audio	AAC, AMR, MP3, M4A, OGG (OPUS, mono)	16 MB	None	A voice note is OGG OPUS with the voice flag
Document	PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT	100 MB	Up to 1,024 characters	Optional filename sets the icon
Sticker	WebP	100 KB static, 500 KB animated	None	WebP is only accepted as a sticker
Location	Latitude and longitude	n/a	n/a	Optional name and address
Contacts	Name, phones, emails, addresses, websites	Up to 257 contacts per message	n/a	A WhatsApp ID adds Message and Save contact buttons
Reaction	One emoji	n/a	n/a	On a received message up to 30 days old
Quoted reply	Any type, with the quoted message’s ID	Per type	Per type	Not for templates or reactions

Two things the table doesn’t show. Every one of these is a free-form message, so it can only go to someone who has messaged you in the last 24 hours. And a file doesn’t change the price: a PDF reply inside the window is a service message like a text reply, charged after a number’s 1,000 free deliveries a month since 1 October 2026, at ₹0.115 per delivered message to an Indian number before GST; the October cost guide has the table.

How do you send a PDF to customers on WhatsApp?

As a document message inside the window, or as a template with a document header outside it.

A document message takes the media ID of an uploaded file, an optional filename with its extension so the phone shows the right icon, and a caption. Meta’s own example is an order confirmation PDF captioned “Your order confirmation (PDF)”. The supported types are PDF, Word, Excel, PowerPoint and plain text, all at 100 MB, and Meta says other types “may be sent via the API, but they are not supported and may not be handled as expected”.

Kavitha’s 14 MB price list is well inside the cap, but the cap is not the question. The question is whether a customer on a weak connection wants to download 14 MB to look at twelve sarees. Our advice: a PDF under 2 MB with the photographs compressed, or one JPEG per category under 1 MB. The PDF wins when the customer will forward it or keep it; the image wins when the customer is deciding now.

Outside the window, the same file goes in a template with a document header. You create the template with the header format set to document and upload a sample file at creation, which Meta’s template-media page calls the header handle. Each send then carries the real file’s media ID. An invoice sent this way as “Your invoice for order {{1}} is attached” is a utility template at ₹0.115 per delivered message in India before GST, and our template examples include the payment and booking templates it belongs beside. A price list with offers in it is marketing at ₹0.8631.

Image, video and voice: the rules that catch people out

The caps are easy; the encoding rules are what fail at upload.

Images must be 8-bit, RGB or RGBA, as JPEG or PNG, under 5 MB. A CMYK JPEG from a designer’s print file fails. Phone photographs often run to 3 to 6 MB, so compress before upload.

Video must use the H.264 video codec and AAC audio, with one audio stream or none, as MP4 or 3GPP under 16 MB. Meta warns that “videos encoded with the H.264 High profile and B-frames are not supported by Android WhatsApp clients”, and recommends the Main or Baseline profile with the moov box placed before the mdat box, which ffmpeg does with its faststart flag. At the bitrate phones record, 16 MB is a short clip; re-encode anything longer at a lower bitrate rather than trimming the ending.

Voice notes are a specific thing. Meta’s audio page, updated 2 July 2026, says a voice message is an OGG file encoded with the OPUS codec, mono, sent with the voice flag set to true. It shows your business’s profile picture with a microphone icon and downloads automatically. Send an MP3 with the voice flag and you get a basic audio message instead, with a download icon and a music note. Two more rules from the page: the play icon only appears if the file is 512 KB or smaller, otherwise the client shows a download arrow, and since 17 March 2026 Meta sends a played status the first time a customer plays a voice message. Meta says the commonest audio errors are a MIME type that doesn’t match the extension and an OGG file not encoded with OPUS.

Location, contact cards, stickers and reactions

A location message carries latitude and longitude with an optional name and address, and the customer sees a map pin. Send the shop’s pin to a first-time visitor. The request runs the other way too: an interactive location request message asks the customer to share theirs, useful for a delivery slot.

A contacts message sends one or more cards with names, phone numbers, emails, addresses and websites, up to 257 per message, though Meta recommends fewer. Include the contact’s WhatsApp ID and the customer gets Message and Save contact buttons; omit it and they get an Invite to WhatsApp button. The sensible use is one card: the branch manager.

Stickers are WebP files, 100 KB static and 500 KB animated, and WebP is accepted only here. A festive sticker from a boutique with its own pack reads as warmth; from a bank, odd.

A reaction is one emoji on a message the customer sent. Meta’s page says the message must be under 30 days old, not deleted and not itself a reaction, or the reaction fails with error 131009, and that a reaction only ever produces a sent status. Reactions stay free after 1 October and don’t count against the 1,000, per Meta’s changelog entry of 29 September 2026.

Text, links and quoted replies

A text message is up to 4,096 characters. Set preview_url to true and WhatsApp tries to render a preview of the first URL in the body; the URL must begin with http:// or https://, and if the preview can’t be fetched the customer sees a plain link. Meta’s link-preview page says the page needs og:title, og:description, og:url and og:image tags within the first 300 KB of its HTML, and an image under 600 KB at least 300 pixels wide. Even then, “it’s not guaranteed to work”. A Shopify product page carries those tags; a shared Drive link usually doesn’t.

A quoted reply sets context.message_id to the customer’s message so your reply shows their words in a bubble above it. Meta lists where the bubble won’t appear: a reaction can’t be a quoted reply, templates don’t show it, and it disappears if the quoted message was deleted or moved to long-term storage, which Meta says typically happens after 30 days.

How media is uploaded, and how long Meta keeps it

You upload a file once to the media endpoint for your phone number, with its MIME type, and Meta returns a media ID. From Meta’s media page: “All media files sent through this API are encrypted and persist for 30 days, unless they are deleted earlier.” Media IDs returned by the API expire after 30 days, and Meta recommends the ID over a public link on your own server, for performance and fewer errors. To fetch a file back, you query the media ID and get a URL valid for 5 minutes, then download it with your access token. You can delete a media ID at any time.

For Kavitha’s price list, a file uploaded on 1 October must be uploaded again by November, and her tool should do that for her. Nothing is “stored by Meta for you”: the Cloud API keeps a file long enough to deliver it, not as your archive. The copy that lasts is in your provider’s media library, and where that is hosted and for how long is a question for the provider; our Cloud API data privacy guide covers what Meta keeps and what to ask.

What customers can send you, and how it arrives

Whatever their phone can send, within Meta’s supported types, arrives on the messages webhook with a media ID. An incoming document, for example, carries the caption, filename, MIME type, a SHA-256 hash, the media ID and a URL. Incoming videos also carry a forwarded flag, and frequently_forwarded if the clip has been forwarded more than five times.

The clock starts there. Meta’s media page says a media ID from a webhook is only available to download for 7 days, through a URL that lasts 5 minutes each time you request it. A customer who sends a UPI payment screenshot on Monday has sent you something your tool must download and keep; by the following Monday it is gone from Meta’s side. Our customer support guide covers routing these chats.

The inbound cap is 100 MB. If a customer sends something larger, you get a webhook with error 131052 and a title that says the file is too big, and Meta suggests warning the customer.

Some things a customer can do in WhatsApp never reach the API. Meta’s unsupported-messages reference lists polls, GIFs, edits, pins, group invites, keep-in-chat and others; they arrive as a message of type unsupported with error 131051. A customer who edits a message after sending has, from your side, sent nothing new.

What’s not on the list

Four things people try and Meta doesn’t list.

GIFs. No Cloud API media table includes a GIF format, and an incoming GIF arrives as unsupported. Meta’s template-media page does say a header can be “an image, video, GIF, or document”, but the GIF header belongs to its separate Marketing Messages API, whose features page, updated 30 June 2026, lists it. Conecxt doesn’t offer that API; our Marketing Messages API guide explains who it is for.

WebP images outside stickers. A WebP product photograph has to be converted to JPEG or PNG first.

Voice notes in any format but OGG OPUS. Everything else becomes a basic audio file.

Files past the caps or with a wrong MIME type. These fail at upload with error 131053, and Meta’s advice is to inspect the file’s real type before blaming the API.

If you run a property team, the twelve templates in our real estate pack show where a brochure PDF or a site video header fits the category rules. For everyone else, three habits cover most of this page: compress the file before upload, give a document a filename a customer would recognise, and test every media message on a cheap Android phone on mobile data before it goes to a list.