WhatsApp Business API enables high-engagement messaging with rich features like images, documents, and interactive buttons.
When to Use WhatsApp
- Customer support: Rich media and quick replies
- Marketing campaigns: Higher open rates than SMS
- Order updates: Detailed information with images
- International messaging: Often cheaper than SMS
Basic WhatsApp Message
curl -X POST https://api.zavu.dev/v1/messages \
-H "Authorization: Bearer zv_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"to": "+56912345678",
"text": "Hello from Zavu!",
"channel": "whatsapp"
}'
Message Types
1. Session Messages
Free-form messages sent within a 24-hour window after the user’s last message.
{
"to": "+56912345678",
"text": "Thanks for reaching out! How can we help?",
"channel": "whatsapp"
}
2. Template Messages
Pre-approved messages that can be sent anytime (outside the 24-hour window).
{
"to": "+56912345678",
"templateId": "tpl_order_shipped",
"data": {
"customerName": "John",
"orderId": "12345",
"trackingUrl": "https://track.co/abc"
},
"channel": "whatsapp"
}
Template messages require approval from Meta before use. Submit templates through your Zavu dashboard.
The 24-Hour Window
WhatsApp enforces a conversation window:
User sends message → 24-hour window opens → You can send session messages
↓
Window expires → Only template messages allowed
| Message Type | Within 24h | After 24h |
|---|
| Session (free-form) | Yes | No |
| Template (pre-approved) | Yes | Yes |
Creating WhatsApp Templates
1. Define Your Template
curl -X POST https://api.zavu.dev/v1/templates \
-H "Authorization: Bearer zv_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"name": "order_shipped",
"category": "transactional",
"body": "Hi {{customerName}}, your order #{{orderId}} has shipped! Track it here: {{trackingUrl}}",
"channels": ["whatsapp"],
"whatsapp": {
"templateName": "order_shipped_v1",
"namespace": "your_namespace"
}
}'
2. Submit for Approval
Templates are automatically submitted to Meta for review. Check status:
curl https://api.zavu.dev/v1/templates/tpl_abc123 \
-H "Authorization: Bearer zv_live_xxx"
{
"whatsapp": {
"status": "approved" // or "pending", "rejected"
}
}
3. Use Approved Template
curl -X POST https://api.zavu.dev/v1/messages \
-H "Authorization: Bearer zv_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"to": "+56912345678",
"templateId": "tpl_abc123",
"data": {
"customerName": "John",
"orderId": "12345",
"trackingUrl": "https://track.co/abc"
}
}'
Template Best Practices
Do’s
- Use clear, specific template names
- Include dynamic variables for personalization
- Keep messages concise and valuable
- Test templates before bulk sending
Don’ts
- Don’t use templates for promotional content without consent
- Don’t include placeholder text like “[insert name]”
- Don’t use excessive capitalization or punctuation
- Don’t send the same template repeatedly to unresponsive users
Template Categories
| Category | Use Case | Approval Speed |
|---|
transactional | Order updates, shipping, receipts | Fast (hours) |
marketing | Promotions, offers, newsletters | Slower (days) |
alert | Security alerts, account notifications | Fast (hours) |
WhatsApp Quality Rating
Meta tracks your messaging quality. Maintain good standing by:
- Getting opt-in consent before messaging
- Respecting user preferences - stop messaging users who don’t respond
- Sending relevant content - avoid spam-like messages
- Responding promptly - engage within the 24-hour window
Low quality ratings can result in reduced messaging limits or account suspension.
Handling Delivery Status
WhatsApp provides detailed delivery status:
| Status | Description |
|---|
sent | Message sent to WhatsApp servers |
delivered | Message delivered to user’s device |
read | User opened the message |
failed | Delivery failed |
Common Errors
| Error | Cause | Solution |
|---|
Template not approved | Template pending/rejected | Wait for approval or fix issues |
Outside 24h window | Session expired | Use a template message |
Invalid phone format | Wrong number format | Use E.164 format |
User not on WhatsApp | User doesn’t have WhatsApp | Fall back to SMS |