Formats and sizes
The template editor accepts these files:
If you pick another file type, Flowella shows Use JPEG, PNG, MP4, or PDF only. If the file is too large, it shows File is too large for Meta’s limits.
Document headers aren’t available for Authentication templates. For text and location headers, see Template reference.
Images
Header images must be JPEG or PNG files, 8-bit, in RGB or RGBA. Convert WebP, HEIC and GIF files before you upload them.Videos
WhatsApp on Android plays MP4 videos that use the H.264 Main or Baseline profile without B-frames, with AAC audio. Videos encoded with the H.264 High profile and B-frames don’t play there. Flowella checks every MP4 you upload in the editor and fixes it when needed:- If the video uses another profile or codec, B-frames, audio that isn’t AAC, or more than one audio track, Flowella re-encodes it.
- If the file’s index (the
moovbox) sits at the end of the file, Flowella moves it to the start.
Documents
PDF is the only document format the editor accepts. Set the Document filename below the upload. It defaults to the uploaded file’s name, and recipients see it on the WhatsApp document bubble. Use a clear name such asAcme-Order-12345-Receipt.pdf, not attachment.pdf.
What doesn’t work
YouTube and Vimeo embeds
YouTube and Vimeo embeds
You can’t embed a YouTube or Vimeo video in a template header. The header has to be an MP4 file.To share a YouTube video, you have two options:
- Put the YouTube link in the body or a URL button. Tapping it opens the YouTube app or a browser.
- Download the video and upload it as an MP4. Do this only if you have the rights to share the video, which usually means it is your own.
GIFs
GIFs
The editor doesn’t accept animated GIFs. Convert the GIF to an MP4 video and upload that instead.
WebP images
WebP images
The editor accepts only JPEG and PNG images. Convert WebP images to JPEG or PNG before you upload them.
HEIC photos straight from an iPhone
HEIC photos straight from an iPhone
iPhones save photos in HEIC format by default, which the editor doesn’t accept. Change the iPhone camera setting to capture in JPEG, or convert the HEIC file to JPEG before you upload it.
Files above the size limit
Files above the size limit
A 6 MB image, an 18 MB video or a 110 MB PDF is rejected. Compress the file before you upload it.
How Flowella handles header media
1
Add the file in the editor
Click New template on the Templates page, or open an existing template. Choose Image, Video or Document as the Header type. Then drag the file onto the upload area, or click Upload a file. For a Document header, check the Document filename.
2
Flowella checks the file
Flowella checks the format and size before it uploads the file, so you see a problem straight away instead of a rejection from Meta later.
3
Flowella uploads the file to Meta
The editor shows Uploading to Meta…, then Sample media uploaded. The file becomes the template’s sample, and Meta reviews it with the rest of the template.
4
Sends use the approved sample
Every send uses the template’s sample file unless you give a different one. For a Document header, every send also uses your Document filename, whether it comes from a HubSpot workflow, a test send, a bulk send or the inbox.
5
Saving an approved template uploads the sample again
Meta rejects its own preview link when you update a template. So when you save an approved template with a media header, or an approved carousel, Flowella downloads each sample from Meta and uploads it again. If Meta’s preview link has expired, the save fails and asks you to upload that file again. Upload it in the editor, then save again.
6
Clone copies the media
When you click Clone, Flowella copies the header file and the Document filename into the new draft. If the copy fails, the editor shows Header media did not copy with this clone. Re-upload the file before publishing. and you can’t publish until you upload the file.
Send a different file
Most sends use the template’s sample file. You can send a different file in these places:
To send a personalised file to each recipient, such as a PDF receipt, send one API request per recipient.
The link you give must:
- Be publicly reachable, without a sign-in, over HTTPS with a valid certificate.
- Return the file itself, not a web page or a redirect.
- Meet the format and size limits on this page.
Design for the WhatsApp screen
These tips don’t appear in Meta’s specification, but they matter in practice:- Text on images. Keep it large and high-contrast. WhatsApp shows the image at about the width of a phone screen, so small text becomes unreadable.
- Safe area. WhatsApp may crop or letterbox the image. Keep the important content near the centre.
- Brand consistency. The header image sits close to your WhatsApp display name and profile photo, so keep them visually consistent.
- First frame of a video. WhatsApp uses the first frame as the still image before the video plays. Don’t open with a black frame or a logo splash. Start on a meaningful image.
Common errors and fixes
Error 131053: mismatched MIME type
Error 131053: mismatched MIME type
The file’s actual type doesn’t match its extension. This often happens when an iPhone photo exported as “JPEG” is actually HEIC, or when a tool renames a
.docx file to .pdf without converting it.Fix: check the file type (on macOS or Linux, run file -I yourfile.png), then export the file again in the right format.Video plays without audio
Video plays without audio
The audio isn’t AAC, or the file has more than one audio track. Flowella fixes this for videos you upload in the editor. For a video you send from your own link, re-encode it:
Video doesn't play on Android
Video doesn't play on Android
The video uses the H.264 High profile with B-frames. Flowella fixes this for videos you upload in the editor. For a video you send from your own link, re-encode it with the Main or Baseline profile and no B-frames, as in the command above.
Public URL fetch failed
Public URL fetch failed
The file can’t be downloaded from the link. Common causes: the link needs a sign-in, the certificate isn’t valid, the server is slow to respond, or the link redirects instead of returning the file.Fix: test the link with
curl -I. Check that it returns status 200 with the right content type and that the certificate is valid. Then try again.Image looks pixelated
Image looks pixelated
The source image is low resolution, or it was enlarged. Upload a sharp image, and don’t enlarge a small one.
Related guides
- Template reference: the template structure this media fits into
- Templates: create and test templates in Flowella
- Bulk send: send a template with a header to many contacts
- Workflow actions: send templates from HubSpot workflows

