Skip to main content
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
All message templates must be submitted to Meta for review and approval before use. This typically takes 24-48 hours.

​
Template Categories

WhatsApp templates are categorized by their intended use:
CategoryDescriptionUse Cases
UTILITYTransactional updatesOrder status, shipping, receipts
MARKETINGPromotional contentSales, announcements, newsletters
AUTHENTICATIONSecurity codesOTPs, verification, password resets
Using a template category that doesn’t match its content may result in rejection or account penalties.

​
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)
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

Create Template
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.
Variable Examples
{
  "type": "BODY",
  "text": "Hi {{customer_name}}, your order #{{order_id}} is ready.",
  "example": {
    "body_text": [["John Smith", "ORD-12345"]]
  }
}
Provide realistic example values that demonstrate your intended use. This helps ensure faster approval.

​
Template Status

Templates go through several status stages:
StatusDescription
PENDINGSubmitted for review
APPROVEDReady to use
REJECTEDFailed review (see rejection reason)
PAUSEDTemporarily disabled by Meta
DISABLEDPermanently 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:
Sync Templates
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:
Sync Response
{
  "added": 3,
  "updated": 1,
  "removed": 0,
  "total": 4
}

​
Updating Templates

Update an existing template’s components:
Update Template
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"]]
        }
      }
    ]
  }'
Updating a template re-submits it for review. The template will return to PENDING status until approved.

​
Linking Templates to Apps

Templates are organization-level resources that can be linked to specific apps for webhook delivery:
Link Template to App
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:
EventDescription
templates.whatsapp.createdTemplate created
templates.whatsapp.updatedTemplate updated
templates.whatsapp.submittedTemplate submitted for review
templates.whatsapp.approvedTemplate approved by Meta
templates.whatsapp.rejectedTemplate rejected by Meta
templates.whatsapp.pausedTemplate paused by Meta
templates.whatsapp.quality_changedTemplate quality score changed
See Webhooks Setup for configuration details.

​
Sending Template Messages

Once approved, send template messages via the API:
Send Template Message
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:
ScoreDescription
GREENHigh quality - low block rate
YELLOWMedium quality - some users blocking
REDLow quality - high block rate, may be paused
Templates with RED quality may be automatically paused by Meta. Monitor quality scores and improve messaging practices if scores decline.

​
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