# WhatsApp Templates

## Why templates exist

Templates are pre-written, reusable WhatsApp messages with personalisation variables, headers, footers, and buttons. Find them under Templates in the top navigation. The same templates are used across the Team Inbox, Broadcasts, WhatsApp Campaigns, the Scheduled sender, and the Flow builder.

WhatsApp does not let a business send whatever it likes, whenever it likes. The platform is built around two ideas you have to understand before you build a single template:

- The 24-hour customer-service window. The moment a customer messages you, a 24-hour window opens. Inside that window you can reply with free-form text, media, interactive messages — anything. The window resets every time the customer messages again.
- Outside the window, you need an approved template. Once 24 hours pass with no inbound message from that customer, free-form sending is blocked. The only way to re-open the conversation — an order update, an appointment reminder, a promotion — is a template message that Meta has pre-approved. This is why outreach, broadcasts, and campaigns all run on templates: they are the sanctioned way to start (or restart) a conversation.

Pre-approval is how WhatsApp keeps spam under control. Meta reviews each template once, up front, and then you can send the approved version to as many opted-in recipients as your messaging tier allows.

> The bottom line: on the official WhatsApp connections, a template is the foundation of any outbound WhatsApp program. Getting templates written, checked, and approved is what makes broadcasts and campaigns possible.

## How templates differ by WhatsApp connection

How a template behaves depends on how your WhatsApp number is connected:

Connection | What a template is | Status
--- | --- | ---
WhatsApp Cloud API (official / Meta) | Submitted to Meta for review. | Meta's real status — Pending, Approved, or Rejected (plus In appeal, Disabled, Paused, Flagged). Only Approved templates can be sent outside the 24-hour window.
Twilio | Linked to a Twilio content template so marketing, utility, and authentication sends route through Twilio. | A status you manage yourself (approved / pending / rejected) for your own workflow.
Unofficial API | No Meta review — sent as an ordinary message with the variables filled in. | A status you manage yourself.

The status tabs (Approved / Pending / Rejected) show Meta's real status on the official Cloud API connection, and your own status on the Unofficial API or Twilio. On the official connection, only templates Meta has actually approved can be picked elsewhere in the app — so a template you marked "approved" on another connection can never accidentally be sent through Meta and fail.

## Template types

The create form supports four types. Pick the type first — the rest of the form adapts to it.

Type | What it is | Typical use
--- | --- | ---
Standard | Header (text or media) + body + footer + buttons. The everyday template. | Order updates, promos, reminders, notifications.
Media | A standard template whose header is an image, video, or document. | Receipts, brochures, banner-led announcements.
Carousel | An intro body above 2–10 swipeable cards. Each card has an image/video, body text, and an identical button shape. | Product lines, destination sets, multi-offer promos.
Authentication | A one-time-passcode template with a copy-code or one-tap OTP button. Must be filed under the AUTHENTICATION Meta category. | Login codes, 2FA, transaction verification.

## Component reference

Every part of a template has a field on the create form and a Meta limit. WaDesk's built-in checker catches any rule break before the template is submitted.

Component | Limit / rules
--- | ---
Name | Lowercase letters, digits, and underscores; up to 60 characters in the form. Whatever you type is tidied into this format and must contain at least one letter or digit.
Category | Marketing, Utility, or Authentication — this is the review path Meta uses. You can also tag an industry (e.g. travel / ecommerce) for your own filtering.
Language | A language code such as `en_US`, `hi_IN`, `pt_BR`, or just `en`.
Header | A text header up to 60 characters with at most one variable; or an image, video, or document file (the type is detected from the file you upload).
Body | Up to 1024 characters. Supports `*bold*`, `_italic_`, and personalisation variables.
Footer | Up to 60 characters. No variables allowed.
Buttons | Up to 10 total. See the button table below for per-type limits.

### Button reference

Button type | Limit & rules
--- | ---
Visit website (link) | Up to 2 per template. The link can be up to 2000 characters. A link with a `{{1}}` variable in it needs an example value.
Call phone | Up to 1. Digits only with an optional leading `+`, 6–15 digits.
Copy code | Up to 1. Needs an example code value.
Quick reply | Text only. Counts toward the 10-button total.
OTP (one-tap / copy) | Authentication templates only. One-tap also needs your Android app's package name and signing key (signature hash).

> Button grouping: Meta requires same-type buttons to be next to each other. An order like website, quick reply, website is rejected — group all your website / phone / quick-reply buttons together. Button labels are capped at 25 characters.

### Placeholders & personalisation

Type placeholders directly in the header or body. You can write them by name (`{{first_name}}`) or by number (`{{1}}`) — when you save, WaDesk converts everything to numbers (`{{1}}`, `{{2}}`, …) in the order they first appear. This is required because Meta rejects named placeholders, so even one stray `{{first_name}}` would fail the whole submission.

WaDesk remembers which contact field belongs to each number, so the right value is filled in for each recipient when the message is sent. If your text already uses numbers, it is left unchanged.

> Placeholder rules Meta enforces (WaDesk blocks these before submission):
> - Body cannot start or end with a placeholder — add text around it (`Hi {{1}}, your order is ready`).
> - No two placeholders back-to-back, even separated by a space (`{{1}} {{2}}`) — put descriptive text between them.
> - Numbers must start at `{{1}}` and run in order with no gaps.
> - The header allows at most one variable; the footer allows none.
> - Meta wants one example value per placeholder. Fill these in or the template scores poorly and may be auto-rejected.

## Create a standard template

1. Go to Templates and click Create Template.
2. Keep the type on Standard (the pill at the top shows the active type).
3. Identity: enter a name (lowercase, e.g. `order_shipped`), pick a category (Marketing / Utility / Authentication — this is the Meta review path), and a language.
4. Header (optional): plain text (max 60, one variable max), or switch to media and upload an image, video, or document. The type is detected from the file.
5. Body: write the message. Use `{{1}}`, `{{2}}` (or named tags) for personalisation, and `*bold*` / `_italic_` for emphasis. Keep it under 1024 characters.
6. Footer (optional): a short closing line — no variables.
7. Buttons (optional): add up to 10 — action buttons (visit website / call phone / copy code) and quick replies, grouped by type and within the per-type limits.
8. Click Submit for review. WaDesk tidies your placeholders, runs its checks, and takes you to the template's detail page.

> Build with AI: the create form has a Build with AI button. Give it a business name, industry, occasion, purpose, call-to-action, and tone, and it returns a ready-to-fill header, body, footer, and buttons (no emojis, within Meta's limits) that you can review and edit. You can only pick the AI providers your admin has enabled.

## Create a carousel template

1. Choose type Carousel on the create form.
2. Write the intro body (shown above the cards). This is mandatory for carousels — Meta rejects an empty top-level body.
3. Add 2 to 10 cards. For each card supply a body (max 160 characters), upload media, and add 1–2 buttons.
4. Click Submit for review.

> Carousel consistency rules (Meta rejects mismatches): every card must use the same media type (all images or all videos), and every card must have the same buttons — same number, same types, same order. Each card needs at least one button and at most two. Card bodies are capped at 160 characters. WaDesk blocks any mismatch before it reaches Meta.

## Create an authentication (OTP) template

1. Choose type Authentication and set the category to Authentication (required — Meta rejects an OTP template filed under any other category).
2. Add exactly one OTP button: copy code or one-tap.
3. For one-tap, supply your Android app's package name (e.g. `com.example.app`) and its signing key (signature hash).
4. Click Submit for review.

> What WaDesk fills in for you: authentication templates have a fixed shape, so WaDesk builds the standard security-notice body, the code-expiry footer, the OTP button, and a short send window for you. At send time you only supply the code once — it's used for both the message text and the button.

## The checker & fixing rejections

Before any template is sent to Meta, WaDesk checks it. The goal is to never let a doomed submission reach Meta, because every rejection lowers your WhatsApp number's quality score — and that slows delivery for every other template on the same number.

The checker reports two levels:

- Errors — block the submission. Clear breaks of Meta's rules.
- Warnings — allow the submission but show a notice. Practices that often (not always) cause rejection or low quality scores.

### Error categories (must fix)

Category | What trips it | Fix
--- | --- | ---
Name / language | Empty name, no letters or digits, or a language that isn't a valid code. | Use a name with letters/digits/underscores and a code like `en_US`.
Body size & spacing | Empty body, over 1024 characters, tab characters, or 4 or more spaces in a row. | Trim to 1024; replace tabs and long gaps with single spaces.
Placeholders | Body starts or ends with a placeholder, placeholders next to each other, gapped or out-of-order numbering, named placeholders, more than one variable in a header, or any variable in a footer. | Wrap placeholders in text, renumber from `{{1}}`, move extras to the body.
Buttons | More than 10 total, more than 2 website, more than 1 phone, more than 1 copy-code, types not grouped, missing label, label over 25 characters, link over 2000 characters, a variable link without an example, or a malformed phone number. | Group by type, stay within the limits, add example values for variable links.
Carousel | Fewer than 2 or more than 10 cards, missing intro body, a card without body / media / button, mismatched media type or buttons, card body over 160 characters, more than 2 buttons per card. | Make every card the same shape and give each one media and a button.
Authentication | Not filed under the Authentication category, no OTP button, or one-tap missing the package name / signature hash. | Set the category and complete the OTP button fields.
Emoji (Marketing) | More than 10 emoji in a Marketing body is rejected (only a warning in other categories). | Trim to 10 or fewer.

### Warning categories (review before submitting)

- Long body — over ~800 characters reads poorly on mobile and scores lower.
- Layout noise — 3+ consecutive line breaks, or ALL-CAPS words (5+ letters) that look like shouting.
- No personalisation in marketing — a Marketing template with no placeholders tends to score lower and is more likely to be marked spam.
- Missing examples — fewer real example values than placeholders. Meta auto-rejects templates with no examples; real examples score far better than filler.
- Trigger phrases — see the warning below.

> Trigger phrases: the linter flags promotional/manipulative wording Meta has historically rejected — guaranteed, 100%, act now, click here, limited time only, winner, congratulations you have won, free money, claim now, risk free, no obligation, lifetime deal, and don't miss. Reword these before submitting.

## Submit to Meta & the approval lifecycle

On the official Cloud API connection — when your admin has turned on Meta submission and a WhatsApp Business Account is connected — saving a template automatically submits it to Meta. The steps are:

1. WaDesk checks the template. Errors stop the submission (your draft is still saved, so you can fix and retry); warnings are shown but allowed.
2. Any header media and carousel images are uploaded to Meta.
3. The template is sent to Meta for review.
4. The template is marked with its Meta status (usually Pending), the category Meta assigned, and the submission time.

You land on the template's detail page, which shows the status. While it's Pending, the page checks with Meta about every 30 seconds so the status flips to Approved or Rejected on its own. The list also refreshes statuses quietly in the background, so you don't have to keep tabs open.

If a submission fails, your draft is still saved — fix the issue and re-submit from the detail page. The detail page also shows the quality score and any rejection reason Meta returns.

> Approval is not instant. Meta review can take anywhere from minutes to about 48 hours. Do not schedule a broadcast against a template until its status is Approved — sending against a not-yet-approved template fails for every recipient (Meta reports it as an unknown template, error #132000).

## Send with variables (per engine)

Once approved, a template can be sent from the Team Inbox / Chat, Broadcasts, WhatsApp Campaigns, the Scheduled sender, and the Flow builder.

When you send, WaDesk fills in your variables. The preview shows the values merged into the header and body (both `{{name}}` and `{name}` styles work), so what you see in the picker is what the recipient gets. For broadcasts and campaigns, each variable is matched to a contact field, so every recipient gets a personalised copy.

Connection | How variables are sent
--- | ---
WhatsApp Cloud API (official) | The values are sent in order to fill the approved template's placeholders, matching the exact placeholder count (a mismatch is rejected by Meta). Media headers carry a media link, and only the buttons that need a value (variable links, quick-reply, copy-code, OTP) receive one.
Twilio | The same values are sent in order against the Twilio content template (its ID looks like `HX` followed by 32 characters).
Unofficial API | The body is filled in and sent as a normal WhatsApp message — there is no Meta template involved.

> Ban safety: outside the 24-hour customer-service window you must use an approved template — free-form bulk sends to cold numbers are the fastest way to get a number flagged. Keep marketing personalised, respect opt-outs, and pace your sends. Broadcasts and Campaigns slow sends down for exactly this reason. Each rejected submission also drags your number's quality score down, which slows delivery for every template on that number.

## Manage, edit & delete

- Edit: editing a template re-tidies the placeholders and re-checks the rules. On the official Cloud API connection, a meaningful change usually means submitting for review again.
- Filter & search: the list filters by category, status, and name, and you can sort by newest / oldest / name.
- Approve / reject (your own): on the Unofficial API and Twilio connections you can set a template's status yourself for your own workflow.
- Delete: removes the template. Templates belong to your workspace — you can't see, edit, or delete another workspace's templates.
- Plan limits: your plan sets how many templates you can create. Ready-made templates supplied by the platform don't count against your limit.