Quick Answer
Every WhatsApp Template Message must contain body text. Media is optional and, if used, appears only in the Header. Supported header formats are JPG/JPEG/PNG for images within 5MB, MP4 videos within 16MB, and documents (PDF) within 10MB.
The new media support lets you create a single WhatsApp template with strict .mp4 or .pdf rules and then, at send time, freely swap that media for additional video or document formats—without asking WhatsApp for re-approval—across Contacts, Retargeting, Standard Campaign workflows and template messages in the Chat Window.
When should I use this guide?
Consult it before submitting a template to be sure your media type, size, and formatting meet WhatsApp rules—avoiding one of the most common rejection reasons.
| Media Type | Supported Formats | Max Size | Ideal Use Case |
|---|
| Image | JPG, JPEG, PNG | 5 MB | Product photos, service visuals |
| Video | MP4 | 16 MB | Demo clips, promotional intros |
| Document | PDF | 100 MB (Public API: 10 MB) | Invoices, brochures, policies |
You cannot send a template with media only—body text is mandatory.
2. Creation vs Sending – The Core Difference
Template Creation (strict): you must upload video as .mp4 and documents as .pdf, respecting the size caps.
Campaign Sending (flexible): just before you hit Send or Schedule, you can replace that media with extra formats (.3gp for video; .txt, .doc, .docx, .xls, .xlsx, .ppt, .pptx for documents) while the original template ID stays the same. The same rule applies when the template is used from:
- Contacts
- Retargeting
- Standard Campaign Flow
- Chat Window (template-based message send)
Video:
| Stage | Allowed Formats | Max File Size | Public API Limit |
|---|
| Template Creation | .mp4 | 16 MB | 10 MB |
| Campaign Sending | .mp4, .3gp | 16 MB | |
Document:
| Stage | Allowed Formats | Max File Size | Public API Limit |
|---|
| Template Creation | .pdf | 100 MB | 10 MB |
| Campaign Sending | .pdf, .txt, .doc, .docx, .xls, .xlsx, .ppt, .pptx | 100 MB | |
4. Step-by-Step Workflow
- Create Template – upload .mp4 (video) or .pdf (document) only.
- Select Template for Campaign – pick it from Contacts, Retargeting, Standard Campaign Flow or the Chat Window.
- Media Mapping – replace the original file with any extra supported format; size caps remain.
- Validate Media – the system checks file type and size. If something is wrong, the upload is blocked or an error appears.
- Send / Schedule Campaign – the message goes out with the new media and is visible to both the end-user in WhatsApp and agents in Live Chat.
5. Rules, Limitations & Error Handling
- Only one media file is allowed in the template header.
- Video must stay ≤ 16 MB; documents ≤ 100 MB. The Public API enforces 10 MB for both.
- Invalid format: upload blocked with an error.
- Oversized file: "File size should be less than or equal to 16 MB" for video, "File size should be less than or equal to 100 MB" for document.
- Live Chat limitation: agents cannot attach new formats via the paper-clip; flexibility comes only through template-based sending.
6. What Happens If You Exceed the Limit?
- Template Rejection: Meta will reject your submission during approval.
- API Error Response: The Cloud API will throw a media size error.
Example Error Response:
{ "error": { "message": "Media file size too large", "type": "OAuthException", "code": 131051, "error_subcod...
7. Example Template Message
Header: Image (product photo)
Body: "Hi {{1}}, your order #{{2}} has been shipped."
Sample values: "Hi Sarah, your order #1234 has been shipped."
8. Compliance Notes
- Body text is mandatory.
- File names should be clean (no spaces, symbols, emojis).
- Media must relate directly to the template content.
- Unsupported formats or oversized files result in rejection.
9. Best-Practice Checklist
- Compress media before upload.
- Include clear body text that explains the attachment.
- Preview the template to confirm correct rendering.
- Avoid unrelated stock visuals.
- Test file size on Wi-Fi and mobile data.
10. Typical Use Cases
- E-commerce – one catalogue template reused with product videos, price sheets or stock lists.
- Sales & Lead Gen – swap in PPT, DOC or XLS proposals without cloning templates.
- Service Providers – send reports in whichever format the client wants.
- Marketing Teams – tailor media per campaign while keeping the same approved copy.
11. Customer & Team Benefits
- Template reusability – "create once, reuse forever."
- Flexible media replacement – no re-approval cycles.
- Reduced operational effort – no duplicate templates to manage.
- Faster campaign execution – swap media and launch immediately.
12. Feature Availability
The enhancement works in template headers used from Contacts, Retargeting, Standard Campaign Flow and Chat Window. It depends on a valid WhatsApp Business API setup, template approval status and media validation rules.