WhatsApp template headers: text, image or document?

A template header can be text, an image, a video, a document or a location. Which one works for Shopify order messages, and why media headers fail to send.

When you create a template in WhatsApp Manager, the first field after the name is Header, with a dropdown: None, Text, Image, Video, Document, Location. It is optional, most people skip it, and the ones who do not often pick Image because a logo above the message looks professional. Then the template is approved, the automation is switched on, and every order confirmation fails. This post is about that dropdown: what each choice does, which ones Beacon Messenger can send, and how to get the effect of a branded header with the option that works.

The four parts of a template

A WhatsApp template has up to four components, and Meta's template components reference lists them in the order the customer sees them.

  • **Header.** Optional. One line of bold text, or a piece of media, above the message.
  • **Body.** Required. The message itself, up to 1,024 characters, with the placeholders for name, order number and so on.
  • **Footer.** Optional. One short grey line under the body, up to 60 characters, with no placeholders.
  • **Buttons.** Optional. Quick replies, a link, a phone number.

The header is the only part that can be something other than text, and the difference between a text header and a media header is larger than the dropdown suggests.

Text headers are part of the template

A text header is up to 60 characters and is shown in bold at the top of the bubble. It may contain one placeholder. Meta reviews it together with the body, and once approved it is fixed: every customer gets the same words, with the one placeholder filled in per order.

For order messages that single placeholder is useful. A header of Order {{1}} confirmed, mapped to the order name, puts #1042 in bold on the first line, which is the line a phone shows in the notification preview. The customer knows what the message is about before opening it.

In Beacon Messenger a text header placeholder appears on the automation's mapping page next to the body placeholders, labelled as a header, and takes any merge field the trigger offers. The variable mapping guide walks through that page.

Media headers are supplied on every send

An image, video or document header works differently. The file you upload while creating the template is a sample for Meta's reviewers. It is not stored as the header. Each time a message is sent, the sender has to attach the actual media, as a link or an uploaded media ID, in the send request. A location header is the same idea with coordinates and an address.

That design exists for businesses that send a different file each time: an airline attaching each passenger's boarding pass, a utility attaching each customer's bill. The header is a slot, and the sending system fills it.

Beacon Messenger fills text slots. It reads the placeholders in a template's header text, body and URL buttons and sends a text value for each. It does not attach images, videos, documents or locations. So a template with a media header reaches Meta without the media it requires, Meta rejects the request, and the row in the message log shows Failed with Meta's error, usually one of the parameter mismatch codes. The error code reference lists them.

Nothing in the template picker warns you, because the template is approved and valid. It is simply a kind of template this app does not send. If you have just switched an automation to a new template and every row fails, open the template in WhatsApp Manager and look at the header type first.

Header types and Shopify order messages in Beacon Messenger
HeaderWhat Meta needs at send timeWorks in Beacon Messenger
NoneNothingYes
Text, no placeholderNothingYes
Text with one placeholderA text valueYes, mapped to a merge field
Image or videoThe media file, on every messageNo, the send fails
DocumentThe file, on every messageNo, the send fails
LocationCoordinates and addressNo, the send fails

What people want from an image header, and how to get it

**A logo.** The customer already sees your logo. Your WhatsApp Business profile photo sits next to your display name at the top of the chat and in the chat list. A logo in the header would show it a second time. Put a good square logo on the profile and the branding is done for every message, including replies. The display name post covers what the customer sees there.

**A product photo.** Tempting on an abandoned checkout message. It would need a different image per checkout, which is the per-send media case above. A URL button to the checkout does the job: the customer taps it and sees the cart with every photo. The button guide explains dynamic URL buttons.

**The invoice as a PDF.** Common in markets where customers expect a document with the order. Link to the order status page from a button. It always shows the current state of the order, including edits and refunds, which a PDF sent at checkout cannot.

**The pickup address.** Put it in the body as text. An address in the body can be long-pressed and opened in a maps app on most phones, and it shows in the notification, which a location card does not.

Text headers that earn their line

A header is worth adding when it says something the first line of the body would otherwise have to. Some that work, with the placeholder mapped to the order name:

  • Order confirmation: Order {{1}} confirmed
  • Cash on delivery: Please confirm order {{1}}
  • Shipping update: Order {{1}} is on its way
  • Abandoned checkout: no placeholder, something like Your cart is saved

Keep the store name out of the header. The customer sees it as the sender. Keep emoji out as well: Meta's rules for header text do not allow emoji, asterisks, other formatting characters or line breaks, and a header that contains them is rejected at submission.

One trap with the placeholder: if the mapped field is empty for an order, Meta rejects the message, because a header parameter cannot be blank. Order name is never empty. Customer first name sometimes is. Use the order name in headers and leave names for the body, where the missing merge fields post explains the fallbacks.

Does a header change the category or the price?

Not by existing. Meta prices a template message by its category and the recipient's country, and a utility template with a text header costs the same as one without. What a header can do is change the category. Meta classifies on content, and a header that sells, 20% off this weekend above an otherwise plain shipping update, is the kind of thing that gets a utility template recategorised as marketing. The category change post covers how that happens and what it costs. A header that names the order is safe.

If you already built a template with an image header

  1. Leave the old template alone. A header type cannot be switched from media to text by editing in place, and the template may be in use elsewhere.
  2. Create a new template with a new name, the same body, and either no header or a text header.
  3. Submit it and wait for approval. Utility templates are often approved within minutes, sometimes longer.
  4. In Beacon Messenger, open the automation, pick the new template and map its placeholders. Choosing a different template clears the old mapping.
  5. Place a test order and check that the row in the log reaches Sent, then Delivered.
  6. Rows that failed while the media template was selected can be retried from the log once the automation points at the new template.

The header is the smallest decision in a template and the one most likely to stop it sending. Choose None or Text, put the order number in it if you use it, and let the profile photo carry the logo.

Questions

Can I send a WhatsApp order confirmation with an image header from Shopify?

Not with Beacon Messenger. A media header needs the image attached to every message at send time, and the app sends text values only. A template with an image, video, document or location header is rejected by Meta when the app sends it. Use a text header or no header.

Why do all messages fail after I switched to a new template?

Check the header type of the new template in WhatsApp Manager. If it is Image, Video, Document or Location, Meta expects media with each message and rejects sends that do not include it. Create a version of the template with a text header or no header and select that in the automation.

What can I put in a WhatsApp template text header?

Up to 60 characters of plain text with at most one placeholder. Emoji, formatting characters and line breaks are not allowed. For order messages, a short phrase with the order number, such as Order {{1}} confirmed, works well because it appears in the phone's notification preview.

How do I show my logo in WhatsApp order messages?

Set it as the profile photo of your WhatsApp Business number. Customers see it beside your display name at the top of the chat and in their chat list for every message you send, so a logo in the template header is not needed.

More guides