Sending Media on the WhatsApp API

Sending a picture is the most ordinary thing anyone does on WhatsApp, which is exactly why the API version of it catches people out. There is an upload step, an identifier with an expiry date, a set of size ceilings that differ per type, and a rendering behaviour for documents that no amount of effort will change.

The limits

The 5 MB image ceiling is the one worth designing around. A photo straight off a modern phone, or a designed card exported at print resolution, will clear it comfortably — and nothing about the file looks wrong until the send fails. Compress on the way in, not on the way out.

Upload, or link

You have two routes to attaching a file, and they fail in different places.

Upload posts the file to Meta and returns a media ID. You then reference that ID when sending. One upload, unlimited sends, no dependency on your own infrastructure during the campaign — which matters more than it sounds when you are sending to a few hundred people at once.

Link passes a public HTTPS URL and lets Meta fetch the file at send time. Nothing to store, but now your host is in the critical path of every message. A slow response or a moment of downtime turns into failed sends.

The rule of thumb: same file to many people, upload it. Unique file per person, link it.

The 30-day expiry that breaks working code

Media IDs expire after 30 days. Uploaded files are stored encrypted and persist for roughly the same period.

This produces one of the more disorienting failures on the platform, because nothing you control has changed. Same code, same file, same template — and sends that worked in April fail in June. It is especially common in event-driven work, where assets get prepared far in advance and the send happens much later.

The fix is a habit rather than a feature: treat a media ID as a short-lived cache entry, not a permanent reference. Re-upload close to the send, store the fresh ID, and never assume an ID from last month is still good. If you persist media IDs in a database, store the upload timestamp beside them so the staleness is visible.

Documents always look like documents

A PDF sent over WhatsApp renders as a plain grey tile with a filename and a download control. No thumbnail, no first-page preview, no styling. This is platform behaviour and it applies regardless of how the PDF was produced.

Two practical consequences. First, the filename is your entire pitch — it is the only content the recipient sees before deciding to tap. Sangeet-Schedule.pdf gets opened; doc_final_v3.pdf does not. Second, if the content genuinely needs to be seen rather than opened, it should not be a PDF. Send it as an image, and accept the 5 MB ceiling as the price of being visible in the chat.

Media in templates

The sibling rule surprises nearly everyone the first time. Because Meta requires a separate approved template per attachment type, one logical message — say a ceremony announcement — becomes up to four submissions that differ only in their header.

Keep the body byte-identical across all of them. If the text drifts between the image variant and the text variant, whatever preview your team looks at will stop matching what guests actually receive, and that is a very hard bug to notice from the inside. More on this in the template guide.