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.

For template best practices and approval tips, see the Approval Tips guide.

Template Lifecycle

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.

curl -X GET "https://api.telnyx.com/v2/whatsapp/message_templates" \
  -H "Authorization: Bearer YOUR_API_KEY"

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}")

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}`));

Filter by Status

# 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

{
  "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.

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

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

Authentication Template

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

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"
          }
        ]
      }
    ]
  }'

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}")

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}`);

Marketing Template

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

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.

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.

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.

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

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"]]
        }
      }
    ]
  }'

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

Delete a Template

Remove a template permanently. This action cannot be undone.

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

Choose the most specific category. Meta may reclassify templates that don’t match their declared category, which can affect pricing and delivery.

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 on the support center.

Multi-Language Templates

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

# 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 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 — Use approved templates to send messages
Approval Tips — Tips for getting templates approved
Quickstart — End-to-end setup guide

​Manage WhatsApp Message Templates

​Template Lifecycle

​List Templates

​Filter by Status

​Response

​Create a Template

​Authentication Template

​Marketing Template

​Utility Template

​Get a Template

​Update a Template

​Delete a Template

​Template Categories

​Authentication Rules

​Naming Rules

​Approval Tips

​Multi-Language Templates

​Error Handling

​Next Steps

Manage WhatsApp Message Templates

Template Lifecycle

List Templates

Filter by Status

Response

Create a Template

Authentication Template

Marketing Template

Utility Template

Get a Template

Update a Template

Delete a Template

Template Categories

Authentication Rules

Naming Rules

Approval Tips

Multi-Language Templates

Error Handling

Next Steps