Skip to main content
A WhatsApp template can carry one image, video or document in its header. The wrong format, a file that is too large or a broken link can make the send fail or the template look unfinished. This page explains which files Flowella accepts, how it handles them and how to send a different file.

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 moov box) sits at the end of the file, Flowella moves it to the start.
When Flowella changes a video, it shows We adjusted this video so it plays on Android WhatsApp. The adjusted file must still be 16 MB or smaller, otherwise you see This video is too large for WhatsApp after preparing it. Use a shorter or smaller file. If Flowella can’t prepare the video, you see This video could not be prepared for WhatsApp. Try a different MP4. This applies to header videos and carousel card videos that you upload in the editor. It doesn’t apply to a video you send from your own URL, so encode that file yourself. See Common errors and fixes.

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 as Acme-Order-12345-Receipt.pdf, not attachment.pdf.

What doesn’t work

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:
  1. Put the YouTube link in the body or a URL button. Tapping it opens the YouTube app or a browser.
  2. 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.
The second option is the only way to show the video inside the conversation.
The editor doesn’t accept animated GIFs. Convert the GIF to an MP4 video and upload that instead.
The editor accepts only JPEG and PNG images. Convert WebP images to JPEG or PNG before you upload them.
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.
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.
Flowella doesn’t re-encode videos that you send from your own link.

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

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.
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:
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.
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.
The source image is low resolution, or it was enlarged. Upload a sharp image, and don’t enlarge a small one.
Last modified on October 30, 2026