Sending Template Messages

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

Parameter	Type	Required	Description
`from`	string	Yes	Your WhatsApp phone number
`to`	string	Yes	Recipient’s WhatsApp number
`type`	string	Yes	Must be `"template"`
`template.name`	string	Yes	Template name as registered with WhatsApp
`template.language`	string	Yes	Language code (e.g., `en_US`, `es_ES`)
`template.variables`	object	No	Key-value pairs for template placeholders

Language Codes

Common language codes:

Language	Code
English (US)	`en_US`
English (UK)	`en_GB`
Spanish	`es_ES`
Portuguese (Brazil)	`pt_BR`
French	`fr_FR`
German	`de_DE`

Template Categories

WhatsApp templates are categorized by purpose:

Category	Use Case	Example
Utility	Transactional updates	Order confirmations, shipping updates
Authentication	Security codes	One-time passwords, verification codes
Marketing	Promotional content	Sales, 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:

Log in to WhatsApp Business Manager
Navigate to WhatsApp > Message Templates
Create a new template with your desired content
Submit for approval (typically 24-48 hours)
Once approved, use the template name in your API calls

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:

Error	Cause	Solution
Template not found	Invalid template name	Verify template name matches exactly
Template not approved	Template pending/rejected	Wait for approval or fix rejection issues
Invalid variables	Wrong number of variables	Match variable count to template
Language not found	Unsupported language	Use an approved language variant

Getting Started

Concepts

Webhooks

SMS

WhatsApp

Calling

Resources

Sending Template Messages

When to Use Templates

Basic Example

Templates with Variables

Request Parameters

Language Codes

Template Categories

Creating Templates

Response

Error Handling

​When to Use Templates

​Basic Example

​Templates with Variables

​Request Parameters

​Language Codes

​Template Categories

​Creating Templates

​Response

​Error Handling

When to Use Templates

Basic Example

Templates with Variables

Request Parameters

Language Codes

Template Categories

Creating Templates

Response

Error Handling