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

# Managing WhatsApp Templates

> Create, manage, and send WhatsApp message templates

WhatsApp message templates are pre-approved message formats required for initiating conversations with users outside the 24-hour messaging window.

## Overview

Message templates are essential for:

* **Transactional Notifications** - Order confirmations, shipping updates, appointment reminders
* **Marketing Messages** - Promotions, announcements, newsletters
* **Authentication** - One-time passwords, verification codes

<Info>
  All message templates must be submitted to Meta for review and approval before use. This typically takes 24-48 hours.
</Info>

## Template Categories

WhatsApp templates are categorized by their intended use:

| Category           | Description           | Use Cases                           |
| ------------------ | --------------------- | ----------------------------------- |
| **UTILITY**        | Transactional updates | Order status, shipping, receipts    |
| **MARKETING**      | Promotional content   | Sales, announcements, newsletters   |
| **AUTHENTICATION** | Security codes        | OTPs, verification, password resets |

<Warning>
  Using a template category that doesn't match its content may result in rejection or account penalties.
</Warning>

## Template Components

Templates consist of multiple components:

### Header (Optional)

The top section of the template. Supports:

* **Text** - Plain text header (max 60 characters)
* **Image** - JPG or PNG image
* **Video** - MP4 video (max 16MB)
* **Document** - PDF document

### Body (Required)

The main message content with support for:

* Plain text (max 1024 characters)
* **Variables** - Dynamic placeholders like `{{1}}`, `{{2}}`, `{{name}}`
* Basic formatting (bold, italic, strikethrough)

### Footer (Optional)

A small text line at the bottom (max 60 characters).

### Buttons (Optional)

Interactive elements:

* **Quick Reply** - Pre-defined response buttons
* **URL** - Link to a website
* **Phone Number** - Click-to-call button
* **Copy Code** - Copy a code to clipboard

## Creating Templates

### Via Dashboard

1. Go to **WhatsApp > Templates** or **Settings > WhatsApp Accounts > \[Account] > Templates**
2. Click **Create Template**
3. Fill in the template details:
   * Name (lowercase, underscores allowed)
   * Language
   * Category
   * Components

### Via API

```bash icon="terminal" title="Create Template" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/organization/whatsapp/templates \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsappBusinessProfileId": "wbp_abc123",
    "name": "order_confirmation",
    "language": "en_US",
    "category": "UTILITY",
    "components": [
      {
        "type": "HEADER",
        "format": "TEXT",
        "text": "Order Confirmed!"
      },
      {
        "type": "BODY",
        "text": "Hi {{customer_name}}, your order #{{order_id}} has been confirmed. Expected delivery: {{delivery_date}}.",
        "example": {
          "body_text": [["John", "12345", "January 20, 2024"]]
        }
      },
      {
        "type": "FOOTER",
        "text": "Thank you for shopping with us"
      },
      {
        "type": "BUTTONS",
        "buttons": [
          {
            "type": "URL",
            "text": "Track Order",
            "url": "https://example.com/track/{{1}}",
            "example": ["12345"]
          }
        ]
      }
    ]
  }'
```

## Variable Samples (Examples)

Meta requires example values for template variables during review. These help Meta understand how your template will be used.

```json icon="code" title="Variable Examples" theme={null}
{
  "type": "BODY",
  "text": "Hi {{customer_name}}, your order #{{order_id}} is ready.",
  "example": {
    "body_text": [["John Smith", "ORD-12345"]]
  }
}
```

<Tip>
  Provide realistic example values that demonstrate your intended use. This helps ensure faster approval.
</Tip>

## Template Status

Templates go through several status stages:

| Status       | Description                          |
| ------------ | ------------------------------------ |
| **PENDING**  | Submitted for review                 |
| **APPROVED** | Ready to use                         |
| **REJECTED** | Failed review (see rejection reason) |
| **PAUSED**   | Temporarily disabled by Meta         |
| **DISABLED** | Permanently disabled                 |

### Handling Rejected Templates

If a template is rejected:

1. Review the rejection reason in the dashboard or API response
2. Modify the template to address the issue
3. Submit a new template with a different name

Common rejection reasons:

* Misleading content or category mismatch
* Missing required components
* Prohibited content (violence, discrimination, etc.)
* Poor example values

## Syncing Templates

If you created templates directly in Meta Business Manager, sync them to Chirp:

```bash icon="terminal" title="Sync Templates" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/organization/whatsapp/templates/sync \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsappBusinessProfileId": "wbp_abc123"
  }'
```

The sync operation returns:

```json icon="code" title="Sync Response" theme={null}
{
  "added": 3,
  "updated": 1,
  "removed": 0,
  "total": 4
}
```

## Updating Templates

Update an existing template's components:

```bash icon="terminal" title="Update Template" theme={null}
curl -X PUT https://api.buildwithchirp.com/v1/organization/whatsapp/templates/{templateId} \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "components": [
      {
        "type": "BODY",
        "text": "Hi {{customer_name}}, your updated order #{{order_id}} details are ready.",
        "example": {
          "body_text": [["John Smith", "ORD-12345"]]
        }
      }
    ]
  }'
```

<Warning>
  Updating a template re-submits it for review. The template will return to PENDING status until approved.
</Warning>

## Linking Templates to Apps

Templates are organization-level resources that can be linked to specific apps for webhook delivery:

```bash icon="terminal" title="Link Template to App" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/organization/whatsapp/templates/{templateId}/apps \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "app_abc123"
  }'
```

When a template is linked to an app:

* Template lifecycle webhooks (approved, rejected, paused) are sent to that app
* Multiple apps can be linked to the same template

## Template Webhooks

Configure webhooks to receive template lifecycle events:

| Event                                | Description                    |
| ------------------------------------ | ------------------------------ |
| `templates.whatsapp.created`         | Template created               |
| `templates.whatsapp.updated`         | Template updated               |
| `templates.whatsapp.submitted`       | Template submitted for review  |
| `templates.whatsapp.approved`        | Template approved by Meta      |
| `templates.whatsapp.rejected`        | Template rejected by Meta      |
| `templates.whatsapp.paused`          | Template paused by Meta        |
| `templates.whatsapp.quality_changed` | Template quality score changed |

See [Webhooks Setup](/whatsapp/webhooks-setup) for configuration details.

## Sending Template Messages

Once approved, send template messages via the API:

```bash icon="terminal" title="Send Template Message" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/organization/whatsapp/templates/send \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "wht_abc123",
    "to": "+15551234567",
    "variables": {
      "customer_name": "John Smith",
      "order_id": "ORD-12345",
      "delivery_date": "January 20, 2024"
    }
  }'
```

## Quality Score

Meta assigns quality scores to templates based on user feedback:

| Score      | Description                                  |
| ---------- | -------------------------------------------- |
| **GREEN**  | High quality - low block rate                |
| **YELLOW** | Medium quality - some users blocking         |
| **RED**    | Low quality - high block rate, may be paused |

<Warning>
  Templates with RED quality may be automatically paused by Meta. Monitor quality scores and improve messaging practices if scores decline.
</Warning>

## Best Practices

1. **Be Clear and Concise** - Keep messages focused and easy to understand
2. **Use Appropriate Categories** - Match template category to actual use
3. **Provide Good Examples** - Include realistic variable examples for review
4. **Respect User Preferences** - Include opt-out instructions where appropriate
5. **Monitor Quality** - Track quality scores and adjust messaging if needed
6. **Test First** - Use test numbers to verify template rendering before production use