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

# WhatsApp Message Templates: Creation and Management

> Message Templates are pre-approved messages required for initiating WhatsApp conversations. Learn how to create, manage, and send templates via Convo.

WhatsApp requires every business to use **pre-approved Message Templates** whenever it initiates a conversation with a user outside an active 24-hour customer service window. Templates protect users from spam and ensure businesses communicate with clear, structured messages. Once Meta approves a template, you can send it at scale through Convo campaigns and the messaging API.

> [!WARNING]
>
> Templates **must be approved** by Meta before they can be sent. Attempting to send a template in `PENDING` or `REJECTED` status will return an error. Additionally, approved templates that accumulate poor user feedback can be paused or removed by Meta — always monitor quality ratings in your dashboard.

***

## Template Categories

When you create a template, you must assign it one of three categories. Meta uses the category to determine pricing and applies different review criteria to each.

| Category | Description | Typical Use Cases |
| - | - | - |
| `TRANSACTIONAL` | Non-promotional messages directly related to an agreed transaction or ongoing relationship. | Order confirmations, shipping updates, appointment reminders, account alerts |
| `MARKETING` | Promotional or informational messages intended to drive engagement or sales. | Product launches, discount offers, loyalty rewards, newsletters |
| `OTP` | Short, time-sensitive one-time password or verification code messages. | Login verification, payment OTPs, account recovery codes |

> [!NOTE]
>
> Meta periodically re-categorises templates automatically. If your template is reclassified, you will be notified and the associated per-conversation charge may change.

***

## Template Types

A template's `type` field controls what media or interactive element appears in the **header** of the message:

| Type | Header Content |
| - | - |
| `TEXT` | Plain text only — no media attachment. |
| `IMAGE` | A JPEG or PNG image displayed above the message body. |
| `VIDEO` | An MP4 video displayed above the message body. |
| `FILE` | A document (PDF, DOCX, etc.) attached to the message. |
| `LOCATION` | A map pin showing a latitude/longitude location. |
| `CAROUSEL` | A horizontally scrollable set of cards, each with its own image/video, body, and buttons. |
| `ORDER_DETAILS` | A structured order summary card (supported in select markets). |

***

## Template Status Lifecycle

After you submit a template for review, it moves through the following statuses:

```text theme={null}
PENDING  ──▶  APPROVED
         └──▶  REJECTED
```

| Status | Meaning |
| - | - |
| `PENDING` | The template has been submitted and is awaiting Meta's review. |
| `APPROVED` | Meta has approved the template. It is ready to be sent. |
| `REJECTED` | Meta rejected the template. Check the `rejected_reason` field for details. |

When a template is `REJECTED`, the `rejected_reason` field on the template object contains Meta's stated reason (e.g., `TAG_CONTENT_MISMATCH`, `INVALID_FORMAT`). Fix the flagged issue and resubmit as a new template.

***

## Template Parameters

Template bodies are written with **numbered placeholders** in double curly braces — `{{1}}`, `{{2}}`, `{{3}}`, and so on. At send time, you supply an ordered array of values that replace these placeholders.

```text theme={null}
Hello {{1}}, your order {{2}} has been shipped and will arrive in {{3}} days.
```

When sent with `["Priya", "#ORD-4521", "2"]`, the delivered message reads:

```text theme={null}
Hello Priya, your order #ORD-4521 has been shipped and will arrive in 2 days.
```

The `sample_text` field stored on a template is a pre-rendered version of the body with example values substituted in — Meta requires sample values during the review process so reviewers can assess the message in context.

> [!TIP]
>
> **Simple TEXT template example**
>
> Here is a minimal template definition for a shipping notification:
>
> ```json theme={null}
> {
>   "name": "order_shipped",
>   "label": "Order Shipped Notification",
>   "category": "TRANSACTIONAL",
>   "type": "TEXT",
>   "language": "en",
>   "text": "Hi {{1}}, great news! Your order {{2}} has been dispatched and is on its way. Expected delivery: {{3}}.",
>   "sample_text": "Hi Rahul, great news! Your order #ORD-9901 has been dispatched and is on its way. Expected delivery: 3 days."
> }
> ```
>
> Supply `template_params: ["Rahul", "#ORD-9901", "3 days"]` when sending this template via a campaign.

***

## Interactive Buttons

Templates can include interactive buttons that appear below the message body. WhatsApp supports several button types:

**Call to Action (CTA)**

CTA buttons let contacts take immediate action directly from the message. You can add up to **2 CTA buttons** per template.

| Sub-type | Description | Example |
| - | - | - |
| `PHONE_NUMBER` | Tapping the button dials a pre-configured phone number. | "Call Support" → `+91 98765 43210` |
| `URL` | Tapping the button opens a URL in the device browser. Can include a `{{1}}` parameter for dynamic URLs. | "Track Order" → `https://track.example.com/{{1}}` |

**Quick Replies**

Quick Reply buttons let contacts send a preset reply with a single tap. WhatsApp allows up to **3 Quick Reply buttons** per template.

```json theme={null}
"quick_replies": ["Yes, confirm", "No, cancel", "Talk to agent"]
```

When a contact taps a Quick Reply, the button text is sent as their message and triggers any matching automation or webhook in your project.

**Carousel**

Carousel templates display a horizontal, scrollable list of cards — each card has its own header (image or video), body text, and up to 2 buttons.

Use cases include product catalogues, feature showcases, and multi-step guides. Each card can carry independent CTA or Quick Reply buttons, giving contacts a tailored action per item.

**Coupon Code**

A special button sub-type `COPY_CODE` that renders a one-tap "Copy code" button beneath the message. The coupon code value is passed as a parameter at send time so every recipient can receive a unique code.

```json theme={null}
{
  "type": "COPY_CODE",
  "coupon_code": "{{1}}"
}
```

**Limited Time Offer**

Combine a promotional message with an **expiration timestamp** to create urgency. WhatsApp renders a countdown timer on the message card, and the offer's `expiration_time_ms` parameter can be set dynamically per send.

***

## Languages

Convo supports over **60 languages** for message templates, matching every locale that Meta's WhatsApp Business Platform accepts.

Common language codes used in template definitions:

| Code | Language |
| - | - |
| `en` | English |
| `en_us` | English (US) |
| `hi` | Hindi |
| `es` | Spanish |
| `pt_br` | Portuguese (Brazil) |
| `ar` | Arabic |
| `fr` | French |
| `de` | German |

You can create multiple versions of the same template in different languages and send each to the appropriate audience segment — Convo will dispatch the correct language variant based on the `language` field specified in your API request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.