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 | What Meta needs at send time | Works in Beacon Messenger |
|---|---|---|
| None | Nothing | Yes |
| Text, no placeholder | Nothing | Yes |
| Text with one placeholder | A text value | Yes, mapped to a merge field |
| Image or video | The media file, on every message | No, the send fails |
| Document | The file, on every message | No, the send fails |
| Location | Coordinates and address | No, 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
- 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.
- Create a new template with a new name, the same body, and either no header or a text header.
- Submit it and wait for approval. Utility templates are often approved within minutes, sometimes longer.
- In Beacon Messenger, open the automation, pick the new template and map its placeholders. Choosing a different template clears the old mapping.
- Place a test order and check that the row in the log reaches Sent, then Delivered.
- 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
- WhatsApp Business app drops order tools: move orders to Shopify
- A customer replied STOP to a WhatsApp order message. Now what?
- WhatsApp marketing templates leave the Cloud API in October 2027
- WABA to Messaging Account: what changes for Shopify WhatsApp
- Order paid later, refunded or edited: which WhatsApp messages send
- Edited your WhatsApp automation? What queued messages send
- How to add a WhatsApp chat button to your Shopify store (2026)
- How to send Shopify order confirmations and shipping updates over WhatsApp with the official Cloud API
- Cash on delivery on Shopify: confirm orders over WhatsApp before you ship
- Recovering abandoned checkouts on Shopify with WhatsApp, the compliant way
- Why WhatsApp apps get your number banned: linked device vs API
- How a "free" WhatsApp app for Shopify ends up charging you
- Por qué una app de WhatsApp "gratis" para Shopify te cobra
- Pushdaddy or SuperLemon alternative: WhatsApp apps compared
- How to verify Shopify WhatsApp notifications were delivered
- Chat button still on your store after uninstalling the app?
- WhatsApp API pricing changes on Oct 1, 2026: Shopify impact
- Setting up the WhatsApp Cloud API with Meta's MCP and an AI agent
- WhatsApp chat outside business hours: what shoppers should see
- WhatsApp product sharing on Shopify: tracking dark social
- WhatsApp template rejected? Fixing Shopify order templates
- One WhatsApp number or two? Shopify notifications & support
- Shopify Canvas and Beacon Messenger: what works today
- Shopify now collects WhatsApp marketing consent at checkout. Here is what it changes
- Split shipments on Shopify: how many WhatsApp updates to send
- WhatsApp's 250-a-day messaging limit and your Shopify store
- WhatsApp, SMS or email for Shopify order notifications?
- WhatsApp is down: what happens to your Shopify order notifications
- Shopify orders with no phone number: why WhatsApp messages get skipped
- Shopify rollout discounts and WhatsApp order messages
- Add a Track order button to WhatsApp order messages
- Which Shopify orders trigger a WhatsApp message?
- The abandoned checkout timer restarts every time the shopper comes back
- Blank names, twelve-item orders: what WhatsApp merge fields fall back to
- Who looked at your customers' phone numbers? The access log behind a WhatsApp app
- Send a WhatsApp test message before your first order: what the Connect and Test buttons check
- Disconnect, update credentials, app secret: what each does
- COD reply not tagged: how Beacon Messenger matches replies
- WhatsApp template language: why name alone is not enough
- Finding one WhatsApp message in the Beacon Messenger log
- WhatsApp automation is On but nothing sends: a checklist
- Mapping WhatsApp template variables to Shopify order fields
- Every WhatsApp chat button setting in the Shopify theme editor
- WhatsApp template examples for Shopify: order, shipping, COD, cart
- The Share on WhatsApp block, setting by setting
- WhatsApp order messages when customers speak several languages
- Reading the Beacon Messenger dashboard: sent, delivered, failed, skipped
- Shopify batch fulfilment: what happens to 250 WhatsApp shipping messages
- WhatsApp template status: approved, pending, paused, disabled, and what sends
- WhatsApp quality rating: the field on the Connected number card
- COD returns (RTO) on Shopify: confirm orders on WhatsApp first
- WhatsApp error codes on failed messages: a reference
- WhatsApp display name: what customers see on your order messages
- Shopify Messaging WhatsApp automations vs Beacon Messenger
- OXXO, bank transfer and pay-later orders: when the WhatsApp confirmation goes out
- How many WhatsApp messages will Black Friday send? Sizing your plan
- WhatsApp usernames and BSUIDs: what changes for Shopify order messages
- Reconciling your WhatsApp bill with the Beacon Messenger log
- Track with Shop vs WhatsApp shipping updates on Shopify
- Meta changed my WhatsApp template from utility to marketing
- Shopify's new app security review: what Beacon Messenger can access
- A shopper cancels their own Shopify order: what WhatsApp sends
- Customer erasure in 5 days: what the WhatsApp log keeps
- WhatsApp INR billing deadline: Indian Shopify stores
- Gift orders on WhatsApp: buyer's phone or the recipient's?
- WhatsApp order messages at night: when each one sends
- Downgrading a WhatsApp app plan after peak season: what changes
- Shopify subscription renewals and WhatsApp order messages