# Templates

> Manage WhatsApp message templates

Source: https://docs.soosh.io/features/templates/

![Templates](https://docs.soosh.io/images/11-templates.png)

## Overview

WhatsApp Message Templates are pre-approved message formats that allow businesses to send notifications and updates to customers. Soosh makes it easy to manage, sync, and use templates across your organization.

## Template Management

### Viewing Templates

The templates page displays all your synced templates from Meta's WhatsApp Business API, including:
- Template name and status
- Category (Marketing, Utility, Authentication)
- Language
- Last updated date

### Syncing Templates

Click the **Sync from Meta** button to fetch the latest templates from your WhatsApp Business Account. This ensures your local templates are always up to date with what's approved in Meta.

### Template Editor

![Template Editor](https://docs.soosh.io/images/12-template-editor.png)

View and manage template details:
- **Header** - Optional header with text, image, video, or document
- **Body** - Main message content with variable placeholders
- **Footer** - Optional footer text
- **Buttons** - Call-to-action or quick reply buttons

## Media Headers (Image, Video, Document)

Templates with an `IMAGE`, `VIDEO`, or `DOCUMENT` header require a **sample media file** that Meta will review along with the template text. Without this sample, Meta will reject the template — and Soosh enforces the same check before submission, so a template with a media header can't be saved or published until you've uploaded one.

### Uploading a sample

1. Pick the WhatsApp account in the Details card. The upload calls Meta's API and needs to know which account it belongs to.
2. In the Header card, change **Header Type** to `Image`, `Video`, or `Document`.
3. Pick a file using the file selector that appears.
4. Click **Upload**. The button stays disabled until you've selected a file. On success a green "Media uploaded" pill appears with a truncated handle (`4::aW1hZ2Uv…`) — that's the reference Meta will use when reviewing.
5. Click **Save**. **The handle is only persisted on save** — leaving the page after upload but before saving will lose the handle and you'll have to re-upload.
6. Click **Publish** (or **Republish** if you're updating an approved template) to send the template + sample to Meta for approval.

### File limits

| Header type | Accepted formats | Max size |
|---|---|---|
| IMAGE | JPEG, PNG | 5 MB |
| VIDEO | MP4 | 16 MB |
| DOCUMENT | PDF | 100 MB |

> **Note:** The sample you upload here is **only used by Meta for template review**. When you actually send a message using the template, the recipient sees the media you supply at send time (via `header_params` in the API or by attaching media in the chat composer) — the sample is not the media that goes out to customers.

> **Careful:** Don't upload customer data or anything sensitive as the sample. Meta's review team will see it. Use a generic placeholder image / document.

## Publishing Templates

The lifecycle of a template is **Draft → Pending → Approved (or Rejected)**:

1. **Create** — fill in the editor and click **Save**. The template lands in your local DB as `DRAFT`. It is not visible to Meta yet, and cannot be used to send messages.
2. **Publish** — click **Publish**. Soosh submits the template (including any media handle) to Meta and the status becomes `PENDING`.
3. **Meta reviews** — typically minutes to 24 hours. The status updates to `APPROVED` or `REJECTED` on the next sync.
4. **Republish** — only `DRAFT` and `REJECTED` templates can be edited and republished. Approved templates are locked except for the body of `MARKETING` and `UTILITY` categories (Meta limits which fields are editable post-approval).

If publish fails with "Template has IMAGE header but no media file has been uploaded", the upload either wasn't completed or wasn't saved — go back to step 4 of [Uploading a sample](#uploading-a-sample).

## Template Variables

Templates support dynamic variables that are replaced with actual values when sending messages.

### Positional Parameters

The traditional format uses numbered placeholders `{{1}}`, `{{2}}`, etc.:

```
Hello {{1}}, your order #{{2}} has been shipped!
```

When sending, you provide values in order:
- `{{1}}` → Customer Name
- `{{2}}` → Order ID

### Named Parameters

Templates also support named parameters for better readability and maintainability:

```
Hello {{customer_name}}, your order #{{order_id}} has been shipped!
```

Named parameters make templates easier to understand and less error-prone when dealing with multiple variables. When creating templates with named parameters:

- Use descriptive names like `{{customer_name}}`, `{{order_id}}`, `{{delivery_date}}`
- Parameter names can contain letters, numbers, and underscores
- Soosh automatically detects whether your template uses positional or named parameters

> **Tip:** Named parameters are recommended for templates with 3 or more variables, as they make the template easier to understand and maintain.

### Header Variables

A TEXT header can contain **at most one** variable — this is a Meta restriction
that Soosh enforces at template creation time. Both positional (`{{1}}`)
and named (`{{season}}`) work; mixing positional and named within the same
template (header + body) is still not allowed.

When sending:
- **API**: pass the value via the `header_params` field on
  [Send Template Message](https://docs.soosh.io/reference/api/messages/#send-template-message). It
  falls back to `template_params` if omitted — convenient for named templates
  where the header variable name doesn't collide with a body variable.
- **Campaigns**: add a `header` column (always before the body parameter
  columns) in your CSV or manual entry. The dialog can generate a sample CSV
  with the right columns for you. See
  [Adding Recipients](https://docs.soosh.io/features/campaigns/#adding-recipients).

## Template Categories

  **Marketing**

    Promotional content, offers, and announcements
  
  **Utility**

    Order updates, confirmations, and notifications
  
  **Authentication**

    One-time passwords and verification codes
  

## Template Status

| Status | Description |
|--------|-------------|
| **Draft** | Local-only draft; not yet submitted to Meta and can't be used to send |
| **Approved** | Template is ready to use |
| **Pending** | Awaiting Meta approval |
| **Rejected** | Template was rejected by Meta |
| **Disabled** | Template has been disabled |

> **Note:** Templates must be approved by Meta before they can be used for sending messages. The approval process typically takes a few minutes to 24 hours.

### Quality Rating

Approved templates carry a **quality rating** reflecting how recipients have
engaged with them — Meta lowers it as customers block or report the template.
Soosh stores this on each template and refreshes it on every **Sync from
Meta**. New templates start at `UNKNOWN` until Meta reports a score.

| Rating | Meaning |
|--------|---------|
| **GREEN** | High quality — low negative feedback |
| **YELLOW** | Medium quality — some negative feedback |
| **RED** | Low quality — high negative feedback; at risk of being paused by Meta |
| **UNKNOWN** | Meta hasn't reported a quality score yet |

## URL Button Variables

Templates can include URL buttons with dynamic variables. For example, a "Track Order" button with URL `https://example.com/track/{{1}}` will prompt you to enter the dynamic URL value when sending the template from the chat view.

When sending via the API, provide button values using the `button_params` field. See the [API reference](https://docs.soosh.io/reference/api/messages/#send-template-message) for details.

## Using Templates

Templates can be used in:
- **Direct Messages** - Send template to individual contacts
- **Campaigns** - Bulk send to multiple contacts
- **Chatbot Flows** - Automated template responses
- **API** - Programmatically via REST API