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

# Sending Template Messages

> Send pre-approved WhatsApp message templates

Template messages are pre-approved message formats required for initiating conversations with users outside the 24-hour customer service window.

## When to Use Templates

WhatsApp requires templates for:

* **Proactive outreach** - Contacting users who haven't messaged you recently
* **Notifications** - Order updates, appointment reminders, shipping alerts
* **Transactional messages** - Receipts, confirmations, account updates

<Info>
  Once a user responds to your template message, you have a 24-hour window to send regular messages without using templates.
</Info>

## Basic Example

```bash icon="terminal" title="Send Template Message" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "template",
    "template": {
      "name": "hello_world",
      "language": "en_US"
    }
  }'
```

## Templates with Variables

Most templates include placeholders for dynamic content:

```bash icon="terminal" title="Template with Variables" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "language": "en_US",
      "variables": {
        "1": "John",
        "2": "12345",
        "3": "$99.00"
      }
    }
  }'
```

For a template like `"Hi {{1}}, your order #{{2}} for {{3}} has been confirmed!"`, this would render as:

> Hi John, your order #12345 for \$99.00 has been confirmed!

## Request Parameters

| Parameter            | Type   | Required | Description                               |
| -------------------- | ------ | -------- | ----------------------------------------- |
| `from`               | string | Yes      | Your WhatsApp phone number                |
| `to`                 | string | Yes      | Recipient's WhatsApp number               |
| `type`               | string | Yes      | Must be `"template"`                      |
| `template.name`      | string | Yes      | Template name as registered with WhatsApp |
| `template.language`  | string | Yes      | Language code (e.g., `en_US`, `es_ES`)    |
| `template.variables` | object | No       | Key-value pairs for template placeholders |

## Language Codes

Common language codes:

| Language            | Code    |
| ------------------- | ------- |
| English (US)        | `en_US` |
| English (UK)        | `en_GB` |
| Spanish             | `es_ES` |
| Portuguese (Brazil) | `pt_BR` |
| French              | `fr_FR` |
| German              | `de_DE` |

## Template Categories

WhatsApp templates are categorized by purpose:

| Category           | Use Case              | Example                                |
| ------------------ | --------------------- | -------------------------------------- |
| **Utility**        | Transactional updates | Order confirmations, shipping updates  |
| **Authentication** | Security codes        | One-time passwords, verification codes |
| **Marketing**      | Promotional content   | Sales, offers, newsletters             |

<Warning>
  Marketing templates require explicit user opt-in and have stricter approval requirements.
</Warning>

## Creating Templates

Templates must be created and approved through the WhatsApp Business Manager before use:

1. Log in to [WhatsApp Business Manager](https://business.facebook.com)
2. Navigate to **WhatsApp > Message Templates**
3. Create a new template with your desired content
4. Submit for approval (typically 24-48 hours)
5. Once approved, use the template name in your API calls

## Response

```json icon="code" title="Response" theme={null}
{
  "id": "msg_wa_2DbBs7GWhGvVNJGrDXr5RG0mBWI",
  "from": "+15551234567",
  "to": "+15559876543",
  "type": "template",
  "status": "queued",
  "timestamp": "2024-01-15T12:00:00.000Z"
}
```

## Error Handling

Common template errors:

| Error                 | Cause                     | Solution                                  |
| --------------------- | ------------------------- | ----------------------------------------- |
| Template not found    | Invalid template name     | Verify template name matches exactly      |
| Template not approved | Template pending/rejected | Wait for approval or fix rejection issues |
| Invalid variables     | Wrong number of variables | Match variable count to template          |
| Language not found    | Unsupported language      | Use an approved language variant          |