On this page
An image, video or document template header needs an uploaded file that meets Meta's own format and size limits, and every variable in the body or header needs a realistic sample value before Meta will review it at all. Both are common, easily fixed causes of a first-template rejection.
Media and samples: first 5 of 6 steps
- 1Choose a media header type
- 2Upload the file
- 3Submit without a header sample for a
- 4For a text header with a variable,
- 5Enter a sample for every body variable
Before you start
- You need "Submit templates to Meta" permission to upload a header file.
- Only Image, Video and Document header types require a file upload; Text headers use plain text, and Location and None headers need nothing here.
- A media header cannot contain a variable at all, since a file has nothing for a placeholder to substitute into; only a Text header supports one variable.
Steps
- Choose a media header type. In the header type picker, select Image, Video or Document. A file picker appears where the text header field would otherwise be.
Upload the file. The file is checked against its actual bytes, not just the browser's claimed file type, before it is accepted. On success, the upload returns two things behind the scenes: a Meta upload handle used only for review, and a public link to the same file hosted separately, which is what an actual send later attaches to the message.
Submit without a header sample for a media header. Unlike a text header, a media header never asks for a sample value, since the file itself is what Meta reviews.
For a text header with a variable, enter its own sample. A text header can carry at most one variable, and it needs its own sample value, entered separately from the body's samples, since Meta reviews the header on its own example content.
Enter a sample for every body variable. Below the body editor, one input appears per
{{n}}variable used. Every one must have a value before you can submit; the builder will not let you skip this.Write a realistic example, not a placeholder. "Sarah," "ORD-20891" or "Saturday, 14 June" pass review far more reliably than "test," "value1" or "xxx," which Meta specifically watches for and can reject with a message-mismatch reason since a reviewer cannot judge a template from placeholder text.
What you will see
The live phone preview substitutes your sample values into the message as you type, so you see exactly what a reviewer, and later a real recipient, would see with realistic data in place of each variable. A template submitted without a required sample is blocked locally before it ever reaches Meta, with the validator naming the specific missing field.
Settings and options
| Header type | Accepted formats | Size limit | Variable allowed |
|---|---|---|---|
| Image | JPEG, PNG | 5 MB | No |
| Video | MP4, 3GPP | 16 MB | No |
| Document | 100 MB | No | |
| Text | Plain text | 60 characters | Yes, at most 1, with its own sample value |
| Location | Fixed map pin | Not applicable | No |
| Setting or field | What it does | Default | |
| --- | --- | --- | |
| Header samples | Sample value(s) for a text header's variable, stored separately from body samples | Required when a text header has a variable | |
| Body samples | One sample value per {{n}} variable in the body | Required for every body variable before submission | |
| Upload handle | Meta's resumable-upload reference, used only for the review process | Generated automatically on upload | |
| Hosted media URL | A public link to the same uploaded file, used when the template is actually sent | Generated automatically alongside the handle |
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| File picker rejects a WebP image | Meta does not accept WebP for a template header, only JPEG and PNG | Convert the image to JPEG or PNG before uploading |
| "Upload the header file before submitting" | An Image, Video or Document header type is selected but no file was uploaded | Upload a file, or switch the header type to None or Text if you do not need one |
| Upload fails with a size-related error | The file exceeds the limit for its type (5 MB image, 16 MB video, 100 MB document) | Compress or re-export the file under the limit |
| "Template has [n] variable(s) but only [m] sample value(s) provided" | One or more body variables have no sample entered | Enter a sample value for every {{n}} variable before submitting |
| Rejected with a message-content mismatch reason | Sample values look like placeholders (test, xxx, value1) rather than realistic content | Replace them with realistic examples: a real-sounding name, order number or date |
| Approved image-header template fails to send | The public hosted link for the uploaded file was not saved alongside the review handle | Re-upload the header file through the builder so both the handle and the hosted link are stored |
Related reading
For the full set of rules each component follows, see headers, body, footer, buttons and carousel, and for what the validator's exact messages mean when a sample or format check fails, see what each validator message means.