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

# Manage WhatsApp Message Templates

> Create, list, update, and delete WhatsApp message templates via the Telnyx API. Includes template structure, category selection, and lifecycle management.

# Manage WhatsApp Message Templates

WhatsApp requires pre-approved message templates for business-initiated conversations. Use the Telnyx Management API to create, review, and manage templates programmatically.

<Note>
  For template best practices and approval tips, see the [Approval Tips](/docs/messaging/whatsapp/manage-templates#approval-tips) guide.
</Note>

## Template Lifecycle

```mermaid theme={null}
graph LR
    A[Create] --> B[PENDING]
    B --> C[APPROVED]
    B --> D[REJECTED]
    C --> E[PAUSED]
    E --> C
    C --> F[DISABLED]
```

Templates must be approved by Meta before they can be used. Review typically takes 24-48 hours.

## List Templates

Retrieve all templates for your WhatsApp Business Account.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.telnyx.com/v2/whatsapp/message_templates" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  from telnyx import Telnyx
  client = Telnyx(api_key="YOUR_API_KEY")

  templates = client.whatsapp.templates.list()
  for template in templates.data:
      print(f"{template.name} ({template.category}) - {template.status}")
  ```

  ```javascript Node.js theme={null}
  import Telnyx from 'telnyx';
  const client = new Telnyx({apiKey: 'YOUR_API_KEY'});

  const { data } = await client.whatsapp.templates.list();
  data.forEach(t => console.log(`${t.name} (${t.category}) - ${t.status}`));
  ```
</CodeGroup>

### Filter by Status

```bash theme={null}
# List only approved templates
curl -X GET "https://api.telnyx.com/v2/whatsapp/message_templates?filter[status]=APPROVED" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Search by name
curl -X GET "https://api.telnyx.com/v2/whatsapp/message_templates?filter[search]=welcome" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```json theme={null}
{
  "data": [
    {
      "id": "019cd44b-3a1c-781b-956e-bd33e9fd2ac6",
      "record_type": "whatsapp_message_template",
      "name": "welcome_message",
      "category": "MARKETING",
      "language": "en_US",
      "status": "APPROVED",
      "components": [
        {
          "type": "BODY",
          "text": "Hello {{1}}! Welcome to our WhatsApp updates.",
          "example": {
            "body_text": [["John"]]
          }
        }
      ],
      "quality_rating": "HIGH",
      "created_at": "2026-03-15T12:00:00.000Z",
      "updated_at": "2026-03-15T14:30:00.000Z"
    }
  ],
  "meta": {
    "page_number": 1,
    "page_size": 20,
    "total_pages": 1,
    "total_results": 1
  }
}
```

## Create a Template

Submit a new template for Meta review.

<Warning>
  Set a display name for the phone number before submitting templates. Templates submitted from numbers without an approved display name are rejected by Meta.
</Warning>

<Warning>
  Always include sample values in the `example` field when your template contains parameters (`\{\{1\}\}`, `\{\{2\}\}`). Templates without examples are typically rejected.
</Warning>

### Authentication Template

Authentication templates include an OTP code with a copy-code button.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.telnyx.com/v2/whatsapp/message_templates" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "login_verification",
      "category": "AUTHENTICATION",
      "language": "en_US",
      "components": [
        {
          "type": "BODY",
          "text": "Your verification code is {{1}}. Do not share this code.",
          "example": {
            "body_text": [["123456"]]
          }
        },
        {
          "type": "BUTTONS",
          "buttons": [
            {
              "type": "OTP",
              "otp_type": "COPY_CODE",
              "text": "Copy Code"
            }
          ]
        }
      ]
    }'
  ```

  ```python Python theme={null}
  from telnyx import Telnyx
  client = Telnyx(api_key="YOUR_API_KEY")

  template = client.whatsapp.templates.create(
      name="login_verification",
      category="AUTHENTICATION",
      language="en_US",
      waba_id="YOUR_WABA_ID",
      components=[
          {
              "type": "BODY",
              "text": "Your verification code is {{1}}. Do not share this code.",
              "example": {"body_text": [["123456"]]}
          },
          {
              "type": "BUTTONS",
              "buttons": [{"type": "OTP", "otp_type": "COPY_CODE", "text": "Copy Code"}]
          }
      ]
  )
  print(f"Template ID: {template.id}, Status: {template.status}")
  ```

  ```javascript Node.js theme={null}
  import Telnyx from 'telnyx';
  const client = new Telnyx({apiKey: 'YOUR_API_KEY'});

  const template = await client.whatsapp.templates.create({
    name: 'login_verification',
    category: 'AUTHENTICATION', 
    language: 'en_US',
    waba_id: 'YOUR_WABA_ID',
    components: [
      {
        type: 'BODY',
        text: 'Your verification code is {{1}}. Do not share this code.',
        example: { body_text: [['123456']] }
      },
      {
        type: 'BUTTONS',
        buttons: [{ type: 'OTP', otp_type: 'COPY_CODE', text: 'Copy Code' }]
      }
    ]
  });
  console.log(`Template ID: ${template.data.id}`);
  ```
</CodeGroup>

### Marketing Template

Marketing templates support rich media headers, body text with parameters, and call-to-action buttons.

```bash theme={null}
curl -X POST "https://api.telnyx.com/v2/whatsapp/message_templates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "spring_promotion",
    "category": "MARKETING",
    "language": "en_US",
    "components": [
      {
        "type": "HEADER",
        "format": "TEXT",
        "text": "Spring Sale!"
      },
      {
        "type": "BODY",
        "text": "Hi {{1}}, enjoy {{2}}% off your next order with code {{3}}. Offer ends soon!",
        "example": {
          "body_text": [["Sarah", "25", "SPRING25"]]
        }
      },
      {
        "type": "FOOTER",
        "text": "Reply STOP to opt out"
      },
      {
        "type": "BUTTONS",
        "buttons": [
          {
            "type": "URL",
            "text": "Shop Now",
            "url": "https://example.com/shop?promo={{1}}",
            "example": ["SPRING25"]
          }
        ]
      }
    ]
  }'
```

### Utility Template

Utility templates are for transactional updates like order confirmations, shipping notifications, and account alerts.

```bash theme={null}
curl -X POST "https://api.telnyx.com/v2/whatsapp/message_templates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_shipped",
    "category": "UTILITY",
    "language": "en_US",
    "components": [
      {
        "type": "BODY",
        "text": "Your order {{1}} has shipped! Expected delivery: {{2}}. Track your package here.",
        "example": {
          "body_text": [["ORD-12345", "March 20, 2026"]]
        }
      }
    ]
  }'
```

## Get a Template

Retrieve details of a specific template by ID.

```bash theme={null}
curl -X GET "https://api.telnyx.com/v2/whatsapp/message_templates/{template_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Update a Template

Edit a template's content. Only templates in `APPROVED` or `REJECTED` status can be updated. Updated templates are re-submitted for Meta review.

<Warning>
  Editing an approved template resets its status to `PENDING` while Meta reviews the changes. Your template will be temporarily unavailable for sending.
</Warning>

```bash theme={null}
curl -X PATCH "https://api.telnyx.com/v2/whatsapp/message_templates/{template_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "components": [
      {
        "type": "BODY",
        "text": "Your order {{1}} has shipped! Estimated arrival: {{2}}.",
        "example": {
          "body_text": [["ORD-12345", "March 22, 2026"]]
        }
      }
    ]
  }'
```

<Tip>
  Edit and resubmit rejected templates rather than creating new ones. Meta enforces a 30-day restriction on reusing template names.
</Tip>

## Delete a Template

Remove a template permanently. This action cannot be undone.

```bash theme={null}
curl -X DELETE "https://api.telnyx.com/v2/whatsapp/message_templates/{template_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Template Categories

| Category           | Use Case                                  | Requires Opt-in | Pricing Tier |
| ------------------ | ----------------------------------------- | --------------- | ------------ |
| **AUTHENTICATION** | OTP codes, login verification             | No              | Lowest       |
| **UTILITY**        | Order updates, shipping, account alerts   | Yes             | Medium       |
| **MARKETING**      | Promotions, newsletters, product launches | Yes             | Highest      |

<Note>
  Choose the most specific category. Meta may reclassify templates that don't match their declared category, which can affect pricing and delivery.
</Note>

### Authentication Rules

* Must contain a one-time code or password
* Must include a copy-code or one-tap button
* Cannot include URLs or media (except the OTP button)
* Limited to one code parameter

### Naming Rules

* Lowercase letters, numbers, and underscores only
* Maximum 512 characters
* Must be unique within your WABA for each language
* Avoid words like `test`, `sample`, `demo` — Meta flags these for extra review

### Approval Tips

* **Always include sample values** — Templates with parameters but no `example` field are almost always rejected
* **Set a display name first** — Templates submitted from numbers without an approved display name get rejected
* **Complete your business profile** — Add website, description, and category before submitting. Incomplete profiles increase rejection rates
* **Edit rejected templates, don't recreate** — Meta enforces a 30-day restriction on reusing template names
* **Match category to content** — Meta may reclassify miscategorized templates, affecting pricing and delivery

For detailed best practices and troubleshooting, see our [WhatsApp Message Templates Guide](https://support.telnyx.com/en/articles/13986483) on the support center.

## Multi-Language Templates

Create the same template in multiple languages. Each language variant is reviewed independently.

```bash theme={null}
# English version
curl -X POST "https://api.telnyx.com/v2/whatsapp/message_templates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_confirmation",
    "category": "UTILITY",
    "language": "en_US",
    "components": [
      {
        "type": "BODY",
        "text": "Order {{1}} confirmed. Delivery by {{2}}.",
        "example": {"body_text": [["ORD-789", "March 20"]]}
      }
    ]
  }'

# Spanish version
curl -X POST "https://api.telnyx.com/v2/whatsapp/message_templates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_confirmation",
    "category": "UTILITY",
    "language": "es",
    "components": [
      {
        "type": "BODY",
        "text": "Pedido {{1}} confirmado. Entrega estimada: {{2}}.",
        "example": {"body_text": [["ORD-789", "20 de marzo"]]}
      }
    ]
  }'
```

## Error Handling

| Error Code | Description                           | Resolution                                   |
| ---------- | ------------------------------------- | -------------------------------------------- |
| `40008`    | Template operation failed (catch-all) | Check template status and Meta error details |
| `10004`    | Missing required parameter            | Ensure all required fields are included      |
| `10032`    | Invalid enumerated value              | Check category and language codes            |

Common issues:

* **Rejected templates**: Review [Template Best Practices](/docs/messaging/whatsapp/message-templates/index) for approval tips
* **Duplicate name**: Template names must be unique per language within a WABA
* **Invalid parameters**: Ensure `example` values match parameter count in template body

## Next Steps

* [Send Messages](/docs/messaging/whatsapp/send-messages/index) — Use approved templates to send messages
* [Approval Tips](/docs/messaging/whatsapp/manage-templates#approval-tips) — Tips for getting templates approved
* [Quickstart](/docs/messaging/whatsapp/quickstart/index) — End-to-end setup guide