Skip to main content
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
Once a user responds to your template message, you have a 24-hour window to send regular messages without using templates.

​
Basic Example

Send Template Message
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:
Template with Variables
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

ParameterTypeRequiredDescription
fromstringYesYour WhatsApp phone number
tostringYesRecipient’s WhatsApp number
typestringYesMust be "template"
template.namestringYesTemplate name as registered with WhatsApp
template.languagestringYesLanguage code (e.g., en_US, es_ES)
template.variablesobjectNoKey-value pairs for template placeholders

​
Language Codes

Common language codes:
LanguageCode
English (US)en_US
English (UK)en_GB
Spanishes_ES
Portuguese (Brazil)pt_BR
Frenchfr_FR
Germande_DE

​
Template Categories

WhatsApp templates are categorized by purpose:
CategoryUse CaseExample
UtilityTransactional updatesOrder confirmations, shipping updates
AuthenticationSecurity codesOne-time passwords, verification codes
MarketingPromotional contentSales, offers, newsletters
Marketing templates require explicit user opt-in and have stricter approval requirements.

​
Creating Templates

Templates must be created and approved through the WhatsApp Business Manager before use:
  1. Log in to WhatsApp Business Manager
  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

Response
{
  "id": "msg_wa_2DbBs7GWhGvVNJGrDXr5RG0mBWI",
  "from": "+15551234567",
  "to": "+15559876543",
  "type": "template",
  "status": "queued",
  "timestamp": "2024-01-15T12:00:00.000Z"
}

​
Error Handling

Common template errors:
ErrorCauseSolution
Template not foundInvalid template nameVerify template name matches exactly
Template not approvedTemplate pending/rejectedWait for approval or fix rejection issues
Invalid variablesWrong number of variablesMatch variable count to template
Language not foundUnsupported languageUse an approved language variant