Official API

WhatsApp Media Template: the header almost no one uses that changes response rates

By VeyloCRM · · 11 min read

Every official API template can have an image, video, or PDF at the top. It’s the feature that most changes reading and response rates without increasing conversation costs, and also the one that trips up many when registering due to a poorly explained example media step. This guide solves the registration issue, shows variable media per contact, and presents the numbers from a comparative campaign.

What is a media template

In the official WhatsApp API, every message initiated by a company must use a Meta-approved model — the template. What many companies don’t know is that this model can have, at the top, a media header: an image, a video, or a PDF document.

The difference in results is significant. A text-only message competes with dozens of others on the customer’s screen. A message with an image takes up more space, is seen before being read, and communicates in one second what the text would take three lines to explain. In product, scheduling, event, and billing campaigns, the media header is often the difference between the person opening or ignoring the message.

It’s also where many get stuck when creating the model. The process of sending example media during registration is poorly explained, the error Meta returns is generic, and it’s common for companies to give up and publish the template with text only — losing performance without knowing why.

This guide explains the three types of headers, what each is for, format and size rules, the example media step that trips up so many, how variable media per contact works, what Meta usually rejects, and how to measure if it was worth it.

It’s worth stating upfront what’s at stake. In operations that measure, switching from a text-only template to one with an image header usually affects two numbers simultaneously: how many people read and how many respond. The conversation cost charged by Meta is the same in both cases, and the artwork cost is one hour of reusable work — making this one of the few changes where the gain doesn’t come with increased expense.

And there’s a feature within this topic that almost no one uses and that changes the entire operation: variable media, which allows sending a different file to each contact using the same approved model. This transforms billing, invoicing, and after-sales because it eliminates manual sending of invoices, receipts, and proofs one by one.

Free reading

Keep reading for free

Fill out once and unlock this and all other blog articles. We charge nothing — we just want to know who we’re writing for.

Takes 20 seconds. Prefer to talk directly on WhatsApp?

The three types of media headers

  • Image. The most used and best effort-to-result ratio. Suitable for product, promotion, menu, visual receipt, invitation, and reminder with brand identity.
  • Video. Works very well for launches, demonstrations, and personal messages from the business owner. Has higher production costs and requires attention to file size.
  • Document. The most underestimated. It’s the correct format for invoices, receipts, contracts, proposals, PDF menus, catalogs, and proofs — everything the customer needs to keep or forward.

There is also the simple text header, which is not media, and the location header, useful for those who deliver or serve in person. The choice is not aesthetic: it’s about what the customer will do with it. If they need to keep it, it’s a document. If they need to understand quickly, it’s an image.

Format and size rules

Exact specifications change over time and must be checked in the official documentation before producing the material, but some principles remain and save rework:

  • accepted formats are limited — JPG or PNG for images, MP4 for video, PDF for documents are the safe path;
  • there is a file size limit, and it’s smaller than most imagine, especially for video;
  • aspect ratio matters: very tall or very wide images are cropped on display, and the crop usually cuts exactly the text someone placed inside the artwork;
  • text inside the image becomes unreadable on small screens, and most reading happens on small screens;
  • videos without sound need to work because many people open without audio.

The practical rule that solves almost everything: test the artwork on your own phone before registering the template. What looks great on a computer often appears cropped on the phone.

How to create artwork that works on this channel

WhatsApp header artwork doesn’t follow the same rules as a social media post, and using the same file in both places is a common mistake. Three differences matter.

The first is space. The header appears small in the conversation list and larger only when the person opens it. This means the main element needs to be recognizable in thumbnail — a product, a face, a brand color — and any small text is useless.

The second is the division of labor between image and body. The image grabs attention; the body informs and convinces. Putting price, deadline, and conditions inside the artwork and leaving the body empty wastes the only part of the message that is searchable, copyable, and readable on any device. The opposite works better: clean image, body with information.

The third is repetition. People who receive multiple campaigns from the same company start ignoring a repeated visual pattern. Varying the image between campaigns while maintaining identity preserves attention — and is cheaper than increasing the base.

A simple practice improves all this: before sending to thousands, send the template to three numbers on your own team, on different devices, and see how it appears in the conversation list, not just inside the open chat. That’s where the decision to open happens.

The example media: the step that trips everyone up

To approve a template with a media header, Meta requires a sample — an example file sent during model creation so the reviewer can see how the message will appear.

This is where most get stuck because the process has two non-obvious steps: the file must be sent beforehand, in a separate step, and the identifier returned by this upload is what goes into the template registration. When someone tries to paste the URL of an image hosted elsewhere or uses an identifier from a previous upload, the response is usually a generic invalid parameter error that explains nothing.

Two practical tips for operators:

  • the example media is just a sample for analysis — it doesn’t need to be the final media you’ll send in each campaign, and in most cases won’t be;
  • if your system doesn’t offer the example media field on the template creation screen, it probably doesn’t support media headers, and that’s a question to ask before contracting.

Fixed media and variable media per contact

Once approved, the template can be sent in two ways regarding media:

  • Fixed media — the same image for the entire list. This applies to promotions, notices, and invitations.
  • Variable media — each contact receives a different file in the header, using the same approved template. This allows sending each client’s invoice, each order’s receipt, each payment’s proof, or each person’s contract.

Variable media is the feature that changes operations the most and is the least known. With it, a company no longer needs a template per client and can have a single "your invoice has arrived" model that delivers the correct file to each person. This transforms billing, invoicing, and after-sales.

The template text also accepts variables, so it’s possible to combine: the person’s name in the body, amount and due date in variables, and the individual PDF in the header.

Variable document in practice: what changes in operations

It’s worth detailing the use case that saves the most time because it often goes unnoticed. A company issuing one hundred invoices per month usually sends each manually: opens the chat, attaches the PDF, writes the text, checks the name. That’s several minutes per client, plus rework when someone gets confused and sends the wrong file to the wrong person — which, in billing, is a serious privacy issue.

With an approved utility template, with a document header and variables in the body, this same operation becomes a batch send: the list includes phone, name, amount, date, and file link for each person, and each contact receives their document with personalized text. What took a shift now takes minutes, and the risk of mixing up files between clients disappears because the link is made by data, not human attention.

Three precautions make this flow work. The file must be accessible for sending at the time of dispatch, with a name that makes sense to the recipient since the file name appears in the chat. The database must be correct because a phone number error in a financial document is more serious than in a promotion. And the template must be in the appropriate category for the content, which in billing and proof usually means utility.

Correct category avoids rejection

Media templates follow the same category rules as any other. Choosing the wrong category is one of the most frequent causes of rejection and, when approved, results in higher costs than necessary.

The simple rule: if the message exists because the customer did something — bought, scheduled, requested, asked for a second copy — it tends to be utility. If it exists to sell, promote, or reactivate, it’s marketing. Trying to classify promotion as utility to pay less is the fastest way to rejection and account wear.

What Meta usually rejects in these templates

  • image content unrelated to the template text;
  • artwork entirely composed of promotional text, seen as an attempt to bypass text analysis;
  • media with sensitive content or that violates platform commerce policies;
  • use of third-party brand, logo, or identity unrelated to the company;
  • promises in the image not supported by the message body;
  • example file too generic, unrelated to the declared use.

Remember the reviewer sees the sample. Sending a random photo just to pass the required field increases the chance of rejection.

When media helps and when it hinders

Not every message improves with an image. Three cases where media hinders:

  • Authentication message, like verification codes, which need to be instant, direct, and distraction-free.
  • Short and urgent message, like "your order is out for delivery," where the image only adds weight.
  • Ongoing conversation, within the service window, where the company can simply send media directly without any template.

And three where it helps a lot: catalog and product, where seeing is deciding; documents the customer needs to keep; and reactivation of cold leads, where the challenge is to make the person stop scrolling.

The calculation that shows if it was worth it

Real comparison of the same reactivation campaign, sent in two batches to equivalent audiences of 2,000 contacts each:

  • Text only: 1,914 delivered, 622 read, 71 responded, 12 sales
  • With image in header: 1,902 delivered, 848 read, 134 responded, 23 sales
  • Conversation costs: practically identical in both cases
  • Artwork cost: 1 hour of work, reusable in other campaigns

The relevant point is that media doesn’t change delivery — it changes reading and response. Those with delivery problems have database and opt-in issues, and no image fixes that. Those with good delivery but low response usually have much to gain from the header.

The most common mistakes

  • Putting all the offer text inside the image, leaving the body empty.
  • Using artwork made for computers, which gets cut off on phones.
  • Sending invoices as images instead of documents, preventing the customer from forwarding or printing.
  • Treating the example media as if it were the final media.
  • Choosing utility category for promotional campaigns.
  • Not testing the message on your own phone before sending to the entire base.

Where to start

Choose a message you already send frequently and turn it into a template with a header; create artwork in the correct format and test it on your phone; register it with example media consistent with real use; run a first campaign comparing it with the text-only version to get your own numbers; and set up the variable document model for billing or proof, which usually has the greatest operational impact. A single well-made individual document template solves a problem many companies still solve by sending files manually, one by one.

Frequently asked questions

How do I add an image to a WhatsApp template?

The template must be created with a media-type header, and Meta requires a sample of the file during creation so the reviewer can see how the message will appear. This is where most get stuck because it has two poorly explained steps: the file must be uploaded beforehand in a separate operation, and the identifier returned by that upload is what goes into the model registration. Pasting the URL of an image hosted elsewhere usually generates a generic invalid parameter error that explains nothing. Remember that the example media is only a sample for analysis and doesn’t need to be the final image for each campaign.

Can I send a different invoice or receipt to each client?

Yes, and this is the most underestimated feature of media templates. Once approved, a document header model can be sent with variable media, meaning each contact receives their file using the same template. Combined with variables in the body, it’s possible to personalize name, amount, and due date in the same message. In practice, a company issuing one hundred invoices per month and sending them one by one manually can now do this in batch, in minutes, eliminating the risk of sending one client’s file to another, which is a serious privacy issue in billing.

When is it not worth adding media to the template?

In three situations. Authentication messages, like verification codes, which need to be instant and distraction-free. Short and urgent messages, like "your order is out for delivery," where the image only adds weight without adding information. And within an already open conversation in the service window, where the company can simply send media directly without using any template. Also remember that media doesn’t improve delivery: if delivery rates are low, the problem is the database and opt-in, and no image fixes that.

One approved model, a different file for each client.

In VeyloCRM you create the template with a media header, send individual invoices, receipts, or proofs in batch, and track delivery, reading, and response for each contact.