Skip to main content

​
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 Message Template Best Practices 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"

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

​
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

CategoryUse CaseRequires Opt-inPricing Tier
AUTHENTICATIONOTP codes, login verificationNoLowest
UTILITYOrder updates, shipping, account alertsYesMedium
MARKETINGPromotions, newsletters, product launchesYesHighest
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 CodeDescriptionResolution
40008Template operation failed (catch-all)Check template status and Meta error details
10004Missing required parameterEnsure all required fields are included
10032Invalid enumerated valueCheck 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