> ## Documentation Index
> Fetch the complete documentation index at: https://doc.convo.co.in/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.
</Warning>

***

## 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.
</Note>

***

## 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.
</Tip>

***

## Interactive Buttons

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

<Tabs>
  <Tab title="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}}` |
  </Tab>

  <Tab title="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.
  </Tab>

  <Tab title="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.
  </Tab>

  <Tab title="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}}"
    }
    ```
  </Tab>

  <Tab title="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.
  </Tab>
</Tabs>

***

## 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.