Skip to content

This term

Template Header

The optional top component of a WhatsApp template: a 60-character text line with one variable, or an image, video, document, GIF or location.

Also called: Header component · Template media header · Text header

Often confused with

Template Body

The required main text of a WhatsApp message template: up to 1,024 characters with variables, formatting and emoji, set between header and footer.

Read the Template Body entry

Follow a document header from definition to chat

6 / 6

PayloadStatement PDF

Enters at the top, travels down through 6 layers

Step a statement PDF down through every layer a media header passes: the format fixed at creation, the review sample, the file attached to each send, and what the customer finally sees.

Hop 6 of 6: the payload is in layer 6, Customer's chat. The PDF appears as a tappable document above the body text, with any buttons below it.

What is a template header?

The template header is the optional first component of a WhatsApp message template, shown above the body. A template can have one header, in one of six formats: TEXT, IMAGE, VIDEO, DOCUMENT, LOCATION or GIF. The format is fixed in the template definition; what fills it — the words, the file or the map pin — can change on every send.

A text header holds up to 60 characters and one variable, for example “Order {{1}} has shipped”, and should not contain Markdown formatting characters. Media headers turn the message into a richer card: an image (JPEG or PNG up to 5 MB), a video (MP4 or 3GPP up to 16 MB) or a document such as a PDF invoice (up to 100 MB). GIF headers are MP4 files up to 3.5 MB and are available only on the Marketing Messages API, and location headers are allowed only in utility and marketing templates.

Media headers are handled twice. At creation you upload a sample file through the Resumable Upload API and pass the returned handle in example.header_handle, so reviewers can see what the header will look like. At send time you supply the real media for that customer in a header component — a public link or an uploaded media id — or, for a location header, latitude, longitude, name and address.

The header is not where the message lives. The body is required, holds up to 1,024 characters and many variables, and carries the substance; the header is a 60-character headline or a visual that frames it. A header that merely repeats the body wastes the most visible line in the bubble.

Key takeaways

  • A template header is the optional top component of a WhatsApp template: TEXT, IMAGE, VIDEO, DOCUMENT, LOCATION or GIF.
  • A text header holds up to 60 characters and one variable, and a template can have only one header.
  • Media headers need a sample uploaded through the Resumable Upload API at creation, and the real media on every send.
  • Header media limits: image 5 MB, video 16 MB, document 100 MB; GIFs are MP4s up to 3.5 MB, on the Marketing Messages API only.
  • Location headers work only in utility and marketing templates, and changing a header's format means an edit and a new review.

How does a template header work?

  1. Step 1

    Choose the format

    Text for a short headline; image or video for visual offers; document for invoices, tickets and statements; location for store or pickup directions (utility and marketing only).

  2. Step 2

    Provide the sample

    For text, write the line and give an example value for its variable in example.header_text. For media, upload a representative file with the Resumable Upload API and pass the handle in example.header_handle.

  3. Step 3

    Submit it with the template

    The header is the first item in components, e.g. { "type": "HEADER", "format": "DOCUMENT", … }. Reviewers judge it together with the body, so the sample should match what customers will really get.

  4. Step 4

    Fill it on every send

    Add a header component to the send request with one parameter of the matching type: text, image, video, document (with an optional filename) or location.

  5. Step 5

    Stay inside the media limits

    Image 5 MB, video 16 MB, document 100 MB. Use fast, publicly reachable HTTPS links, or upload once and reuse the media ID — uploaded media IDs stay valid for 30 days.

A template header: key facts and limits

Formats
TEXT, IMAGE, VIDEO, DOCUMENT, LOCATION, GIF
Per template
At most one header
Text header
60 characters, 1 variable
Image
JPEG or PNG, up to 5 MB
Video
MP4 or 3GPP, up to 16 MB
Document
PDF and Office formats, up to 100 MB
GIF
MP4 up to 3.5 MB, Marketing Messages API only
Location
Utility and marketing templates only

A template header in code

{
  "name": "monthly_statement",
  "language": "en_IN",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "format": "DOCUMENT",
      "example": { "header_handle": ["{SAMPLE_FILE_HANDLE}"] }
    },
    {
      "type": "BODY",
      "text": "Hi {{1}}, your statement for {{2}} is attached. Amount due: {{3}} by {{4}}. Pay in the app to avoid a late fee.",
      "example": { "body_text": [["Asha", "October 2026", "INR 1,240.00", "5 November"]] }
    }
  ]
}

{SAMPLE_FILE_HANDLE} is the handle the Resumable Upload API returns for the sample PDF — not a media ID.

Common mix-ups

Common mistakes with a template header

  • Uploading the sample the wrong way

    Template samples need a handle from the Resumable Upload API in header_handle. A media ID from the messages media endpoint is for sending, not for creating templates.

  • Sending without the header parameter

    A template approved with a media header needs that media on every send. Leaving out the header component, or sending a different media type, makes the send fail.

  • Overloading the text header

    Sixty characters includes the variable's value. A long product or customer name in {{1}} can push it over, so keep the fixed text short.

  • Slow or private media links

    WhatsApp fetches link media itself. Links behind a login, signed URLs that expire too soon or slow servers cause failed deliveries; for bulk sends, upload once and reuse the media ID.

  • Assuming GIF headers work everywhere

    GIF headers are available only on the Marketing Messages API. On other routes, use a short video header instead.

Example: A statement PDF and an outage headline

A Pune electricity-bill payments app sends a monthly utility template with a DOCUMENT header. At creation the team uploads a sample statement through the Resumable Upload API and submits its handle. Each month the send request attaches the customer's own statement by link with a filename such as “Statement-Oct-2026.pdf”, so it arrives as a tappable document above a body that states the amount and due date. A second template for outage alerts uses a TEXT header instead — “Power cut in {{1}} today” — because a one-line headline is faster to scan than an attachment when the lights have just gone out.

Template Header FAQs

Can a template have both a text header and an image?+
No. A template has at most one header, in one format. If you need an image and a headline, use the image header and open the body with the headline.
Does the header image have to be the same for every customer?+
No. The sample is fixed at creation, but each send can carry any image that fits the limits — a different product photo per customer, for example.
Can a text header have more than one variable?+
No, one variable at most. Put the second dynamic value in the body, which supports multiple variables, and keep the header to a short headline.
Why does my template need a sample file?+
Reviewers need to see what the header will look like next to the body. You upload the sample once through the Resumable Upload API and pass its handle as `header_handle`.

Rules of thumb

Best practices for a template header

  • Use a document header for anything the customer may want to keep: invoices, tickets, policy documents.
  • Always pass a filename with document headers so the file saves with a meaningful name.
  • Make the review sample representative — a blank placeholder image invites questions at review.
  • Reuse one uploaded media ID across a broadcast instead of making WhatsApp fetch the same link thousands of times.

Why the difference matters

Why does a template header matter?

The header decides what a customer sees first in a busy chat list. An invoice PDF that opens in one tap, a product photo on an offer, or a short “Payment due tomorrow” line all change whether a message gets read and acted on. Getting the format right at creation matters, because it cannot be swapped at send time: a template approved with an image header needs an image on every send, and changing the format means editing the template and going back through review.

See InfiQ pricing

Try it on the official WhatsApp Business API

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms