> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Your first WhatsApp template

> Create, validate, and submit your first WhatsApp message template in Switchbord — from blank editor to Meta approval.

This walkthrough takes you from a blank template editor to an approved WhatsApp template in about fifteen minutes. You only need a connected WhatsApp Business Account (WABA) and an operator with settings access.

## What is a WhatsApp template

A WhatsApp template is a reusable message definition that Meta pre-approves before you can send it. Every **outbound business-initiated message** — a booking confirmation, an invoice notification, a seasonal promotion — must reference an approved template. The template carries the structural shell (text, buttons, header media) and your runtime code fills in the `{{1}}`, `{{2}}` placeholders per recipient.

Templates are the only way to re-engage a contact outside the 24-hour customer-service window, so a clean, approved library is the foundation of every campaign and journey you will run on Switchbord.

## Why templates need Meta approval

WhatsApp is a consent-first channel. To protect users from spam, Meta requires every business template to go through a pre-approval pipeline that checks:

* **Structure** — placeholders are well-formed, examples are realistic, the body does not start or end with a variable, buttons are within limits.
* **Category fit** — the content actually matches `UTILITY`, `MARKETING`, or `AUTHENTICATION`.
* **Policy** — no prohibited industries, no misleading claims, opt-out present on marketing.

You cannot ship a template that has not cleared this review. The Switchbord editor runs the same structural checks locally before it submits, so the majority of violations are caught before Meta ever sees the payload. See [Template rules reference](/whatsapp/template-rules) for the full list.

## Step by step

### 1. Open the template editor

<Steps>
  <Step title="Open Templates">
    From the left sidebar, click **Templates**. You will see the library of templates this workspace has already submitted, filterable by status (`draft`, `pending_approval`, `approved`, `rejected`).
  </Step>

  <Step title="Start a new draft">
    Click **New template** in the top right. A blank editor opens with four panels: metadata, components, preview, and validation.
  </Step>
</Steps>

### 2. Pick a category

The category drives billing, approval tolerance, and which components you can use.

| Category         | Use when                                     | Billing tier     |
| ---------------- | -------------------------------------------- | ---------------- |
| `UTILITY`        | Order, booking, invoice, appointment updates | Lowest           |
| `MARKETING`      | Promotions, campaigns, re-engagement         | Highest          |
| `AUTHENTICATION` | One-time codes, MFA                          | Fixed per-region |

Pick the one that matches the **intent** of the message, not the content. Writing "20% off" in a `UTILITY` template will either be rejected or silently re-categorised by Meta. See [Marketing templates](/whatsapp/marketing-templates) for the full decision tree.

<Tip>
  Leave **Allow category change** enabled on marketing drafts. It lets Meta auto-correct the category during review instead of rejecting outright.
</Tip>

### 3. Write the body with variables

Compose your body text and use `{{1}}`, `{{2}}`, `{{3}}` for runtime substitutions.

```text Example body theme={null}
Ciao {{1}}, la tua prenotazione per {{2}} è confermata. Il codice è {{3}}.
```

Three rules to internalise from day one:

1. **Never start or end the body with a placeholder.** Prefix it with a greeting, suffix it with a full stop plus context.
2. **Never put two placeholders adjacent** with only whitespace or punctuation between them (`{{1}}, {{2}}`). Put at least one word between them.
3. **Number sequentially** starting at `{{1}}`. No gaps, no repeats.

The live validator panel highlights violations inline and links to the exact rule.

### 4. Add examples for every variable

Every `{{n}}` needs a realistic example value. Meta uses these to judge whether the template matches the category and to render a preview during review.

```json Example body_text payload theme={null}
"example": {
  "body_text": [["Marco Rossi", "Roma — Hotel Colosseo", "GBV-2025-0042"]]
}
```

Avoid:

* Bare numbers (`"20"`, `"5"`)
* Single symbols (`"%"`, `"€"`)
* The literal placeholder text (`"{{1}}"`)
* URLs if the body contains none

Bake the unit into the example itself — write `"20%"` for the body fragment `"sconto del {{1}}"`, not just `"20"`.

### 5. Submit

Click **Submit for approval**. Switchbord runs the final client-side validation, then `POST`s to Meta's `/message_templates` endpoint. On success the local status flips to `pending_approval` and the template disappears from the drafts filter.

## What happens next

Meta's review is almost always fast:

* **Minutes** for well-formed `UTILITY` templates that match the category.
* **An hour or two** for `MARKETING` templates that go through content review.
* **Up to 24 hours** under load or when a human reviewer is pulled in.

You do not need to poll. Our webhook handler listens for the `message_template_status_update` event and flips the row to `approved`, `rejected`, or records a category migration. The Templates list updates in real time via Supabase Realtime.

## If the template is rejected

A rejection is not a failure — it is just a checklist item. Switchbord stores Meta's human-readable reason in the `rejection_reason` column and surfaces it at the top of the editor.

<Steps>
  <Step title="Read the error">
    Open the rejected template. The red banner shows Meta's `error_user_msg` verbatim — e.g. *"Variable parameters cannot be next to each other."*
  </Step>

  <Step title="Match it to a rule">
    Every message maps to a rule on the [Template rules](/whatsapp/template-rules) page. The validator error code is in the URL anchor.
  </Step>

  <Step title="Fix and resubmit">
    Duplicate the rejected template (the original is locked), apply the fix, and click **Submit for approval** again. There is no penalty for resubmitting — Meta rate-limits at 100 templates/hour per WABA, which is plenty.
  </Step>
</Steps>

<Tip>
  If the same template is rejected twice for different reasons, that usually means the first fix masked a second violation. Run **Validate** (dry-run linter, no Meta call) to catch both before resubmitting.
</Tip>

## Next steps

* [Template rules reference](/whatsapp/template-rules) — every validator rule, with DO and DON'T examples.
* [Marketing templates](/whatsapp/marketing-templates) — deep-dive on MARKETING category, opt-out, and category migration.
* [Template API endpoints](/api-reference/template-endpoints) — automate template management from your own scripts.