> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.
# WhatsApp template reference: categories, headers, buttons
> Reference for WhatsApp template categories, header formats, button types, variable syntax, coupon and location templates, and the submission lifecycle.
This page is a reference for the building blocks of a WhatsApp template — categories, headers, body, buttons, variables, advanced template types, and the submission lifecycle. For the step-by-step of creating and testing a template, see [Templates](/app/templates). For media format limits, see [Media headers](/app/media-in-template-headers).
## Categories
Every template has exactly one category, set when you submit it to Meta. The category drives **pricing** and **what content is allowed**.
| Category | Use it for | Notes |
| ------------------ | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **Marketing** | Promotions, offers, event invites, re-engagement | Most expensive tier; subject to opt-in rules |
| **Utility** | Order updates, account alerts, reminders, follow-ups to a user-initiated flow | Cheaper than Marketing; content must relate to a specific transaction or request |
| **Authentication** | One-time passwords and account verification codes | Strict format; no marketing content allowed; cheapest tier |
If Meta thinks your template doesn't match the category you picked, it will be **rejected** or **re-categorised** — common with Marketing content submitted as Utility. The category can also change automatically as Meta observes usage patterns, which then changes the rate you're charged.
## Header formats
A template's header is optional. When present, it can be one of:
* **TEXT** — short string, may include one variable.
* **IMAGE** — JPEG or PNG, max 5 MB. See [Media headers](/app/media-in-template-headers).
* **VIDEO** — MP4 or 3GPP with H.264/AAC, max 16 MB.
* **DOCUMENT** — PDF (most reliable), Office formats, or plain text. Max 100 MB. The filename is visible to the recipient.
* **LOCATION** — latitude, longitude, name, and address. Useful for store visits or delivery confirmations.
Media headers can be attached either as a **media handle** (uploaded once to Meta) or as a **public HTTPS URL** fetched per send. See [Media headers](/app/media-in-template-headers) for the trade-offs.
## Body and variables
The body is the main message text. Variables use **double curly braces with a 1-based index**:
```text theme={null}
Hi {{1}}, your order {{2}} has shipped. Track it here: {{3}}
```
Rules:
* Numbers must be sequential starting from `{{1}}` — you cannot skip indexes.
* Provide a sample value for every variable when you submit. Meta uses the samples to evaluate the template.
* Keep variables to short, predictable values. Long pasted blocks are a common rejection reason.
The same `{{n}}` syntax is used in **TEXT headers** and **URL buttons** (see below).
### Formatting in the body
WhatsApp supports a limited set of inline formatting in template bodies:
* **Bold** with `*asterisks*`
* **Italic** with `_underscores_`
* **Strikethrough** with `~tildes~`
* **Monospace** with triple-backticks
Use formatting sparingly. Templates with heavy formatting are often rejected as looking spammy.
## Footer
Optional plain text shown after the body. No variables, no formatting.
## Buttons
A template can include up to **10 buttons total**, grouped as either quick replies or call-to-action. The combinations Meta allows have shifted over Cloud API versions; the most reliable patterns:
| Button type | What it does | Example | Variable? |
| ---------------- | ------------------------------------------------- | ------------------------------- | ----------------------------- |
| **QUICK\_REPLY** | Sends a pre-set text reply back to your business | `Yes, that's me` | No |
| **URL** | Opens a web page | `https://acme.com/orders/{{1}}` | One in the URL |
| **PHONE** | Calls a phone number | `+44 20 7946 0000` | No |
| **COPY\_CODE** | Copies a code to the clipboard | `SAVE20` | One for the code |
| **FLOW** | Opens a WhatsApp Flow | (linked Flow ID) | Variables via the Flow itself |
| **CATALOG** | Opens your WhatsApp catalog | (linked catalog ID) | No |
| **MPM** | Multi-Product Message launcher | (catalog products) | No |
| **VOICE\_CALL** | Initiates a WhatsApp voice call (where supported) | (your business number) | No |
Quick reply buttons are useful when you want a structured response (good for analytics). URL and phone buttons are useful for routing recipients off WhatsApp into your stack. FLOW buttons are the gateway into HubSpot-form-driven Flows that Flowella specialises in.
## Specialised template types
Meta has several specialised marketing template types that bundle extra functionality on top of the base structure.
### Carousel templates
A carousel template shows multiple cards in a horizontal scroll, each with its own media, body, and buttons. Useful for catalog showcases, multi-product offers, or feature comparisons.
* **Up to 10 cards** per template.
* Each card has its own image or video header (one media type per template — all images or all videos, not mixed).
* Each card can have up to **2 buttons** (Quick Reply, URL, or Phone).
* The body of each card can have up to 3 variables.
Approval is per-template (not per-card), so all cards must comply with the chosen category.
### Limited-time offer (LTO) templates
LTO templates render a countdown timer beneath the body. Once the timer expires, the offer is shown as expired and tapping the CTA does nothing.
* A **deal code** parameter is required and shown to the user.
* An **expiration epoch (in seconds)** is required.
* The CTA button is usually a Copy Code or URL.
Best for genuine time-limited offers — using LTO for offers that don't actually expire causes user complaints and category re-categorisation away from Marketing.
### Coupon code templates
Like LTO but without the countdown — just a code the user can copy with one tap.
* The code can be **up to 20 characters** (recently increased from 15).
* The Copy Code button copies the value supplied at **send time** — the template's `example` field is a placeholder only and is never sent.
* In **Templates → Send tab** and the **inbox template dialog**, coupon-code templates surface a dedicated **Coupon code buttons** input where you type the codes you actually want to send (one per recipient row for bulk sends). Older "Copy code" / "Copy coupon code buttons" labels have been replaced with this single, consistent term.
### Authentication templates
Specialised templates for OTP delivery. Three sub-types:
* **One-tap autofill** — uses Android's autofill API to populate the OTP automatically when the user taps the button. Best UX where supported.
* **Copy code** — shows a Copy button; user pastes the code into your app. Works everywhere.
* **Zero-tap** — for trusted senders, the OTP can be delivered without any tap (an automatic API callback from the WhatsApp client to your app). Strict eligibility.
Authentication templates have the cheapest per-message price but the strictest content rules: no marketing content, no extra body copy beyond the code itself.
### Location templates
Carry a pinpoint location in the header, useful for store visits, delivery confirmations, or event venues. The user can open the location in their map app with one tap.
**Location header as variables**
The LOCATION header carries up to four fields — **latitude**, **longitude**, **name**, and **address** — and Flowella treats all four as normal template variables.
* The values you typed in the editor (under `_flowellaEditor.headerLocationPreview`) become the **default** sent if no override is supplied.
* The **Test Template** and inbox send dialogs expose the four fields as regular variable inputs.
* HubSpot's [Send WhatsApp Template](/hubspot/workflow-actions#send-whatsapp-template) action passes the four values through `headerLocation` so a workflow can personalise the pin per recipient.
If you omit any of the four at send time, Flowella falls back to the editor preview value for that field.
## Submission lifecycle
When you submit a template from Flowella, it moves through these states:
Saved in Flowella but not yet sent to Meta.
Submitted to Meta and under review. Most templates clear Meta's automated review within minutes, but some are routed for human review. Flowella's editor tells you approval **may take up to 12 hours** and **emails you** the moment the status changes — you don't need to keep refreshing.
Live and usable. You can send it from the inbox, the API, and HubSpot workflows.
Meta declined the template. The rejection reason appears on the template page. Edit and resubmit.
Meta has reviewed quality feedback and flagged the template. Usually a precursor to PAUSED.
Meta has temporarily restricted sending the template, usually because of recipient feedback or low quality. Comes back automatically if quality recovers.
Meta has permanently restricted the template. Must be resubmitted as a new template (often re-categorised) if you want to use the content again.
## Quality rating
Once approved, each template builds up its own quality rating — separate from the [phone number quality rating](/meta/quality-score). The template-level rating uses the same Green/Yellow/Red scale and is driven mostly by:
* Block rate among recipients
* Frequency of "Report" actions in WhatsApp
* Sustained low engagement (no replies, no link clicks)
Yellow and Red template ratings can cause Meta to pause the template even if the phone number's own rating is Green. Watch template quality in **Flowella → Templates** alongside the number-level rating.
## Time-to-live (TTL)
Templates can have a **time-to-live** that controls how long Meta will attempt delivery before giving up. Useful for time-sensitive sends like flash sale invitations.
* **Default:** 30 days for most templates.
* **OTP / authentication templates:** much shorter (a few minutes by default), since codes have no value once stale.
* **Custom TTL:** can be set per-send for some template types.
If a template expires before delivery (recipient phone offline, account paused, etc.), it counts as a send for billing but never reaches the customer.
## Common rejection reasons
* **Promotional content submitted as Utility.** Re-submit as Marketing.
* **Variable samples that don't match the body** — for example, samples that contain links the body doesn't justify.
* **Body or header text that looks like spam** — excessive capitalisation, "Click here", "Free!!!", multiple exclamation marks.
* **Broken or unreachable media header URLs.**
* **Footer text that contradicts the body.**
* **Generic templates** that could be sent by anyone — `Hi {{1}}, special offer for you` without specifics is too generic for marketing approval.
* **Variables in the wrong context** — using a variable in a place Meta doesn't allow it (e.g. some button types).
* **Display name doesn't match the brand** of the template content. If the WABA's display name is "Acme" and the template promotes "Beta Co", it'll be rejected.
Edit a copy of an APPROVED template rather than the original, so you keep a working version while Meta reviews changes. Flowella's **Templates → Duplicate** does this for you.
## Related guides
* [Templates](/app/templates) — the step-by-step of building a template
* [Media headers](/app/media-in-template-headers) — media format reference
* [Template rejected](/troubleshooting/template-rejected) — diagnosing rejections
* [Quality score](/meta/quality-score) — how phone-number quality interacts with template quality
* [Messaging limits](/meta/messaging-limits) — the tier system that constrains how many templates you can send