Skip to main content

​
Templates

Templates are pre-approved message formats that allow you to send structured messages, especially important for WhatsApp which requires template approval for business-initiated conversations.

​
Why Templates?

Templates solve two key problems:
  1. WhatsApp Compliance: Meta requires businesses to use approved templates when initiating conversations outside the 24-hour window
  2. Consistency: Ensure your transactional messages follow a consistent format

​
Template Structure

A template consists of: 
{
  "id": "tmpl_abc123",
  "name": "order_confirmation",
  "language": "en",
  "body": "Hi {{1}}, your order {{2}} has been confirmed!",
  "category": "UTILITY",
  "variables": ["customer_name", "order_id"],
  "status": "approved"
}

​
Fields

FieldDescription
nameUnique identifier (lowercase, underscores)
languageLanguage code (e.g., “en”, “es”, “pt”)
bodyMessage text with variable placeholders
categoryWhatsApp category (see below)
variablesList of variable names for documentation
statusApproval status

​
Template Variables

Templates support dynamic content through variables. Two formats are supported:

​
Numbered Variables (WhatsApp Native)

Use {{1}}, {{2}}, {{3}} for WhatsApp compatibility: 
"Hi {{1}}, your order {{2}} ships on {{3}}"

​
Named Variables

Use {{name}} for better readability: 
"Hi {{customer_name}}, your order {{order_id}} ships on {{date}}"
Named variables are automatically converted to numbered format when sending via WhatsApp.

​
WhatsApp Categories

WhatsApp requires every template to be categorized:
CategoryUse CaseExamples
UTILITYTransactional messagesOrder confirmations, shipping updates, appointment reminders
MARKETINGPromotional contentSales, offers, newsletters
AUTHENTICATIONVerification codesOTPs, login codes, 2FA
Marketing templates have stricter approval requirements and may have different pricing. Use UTILITY for transactional messages.

​
WhatsApp Approval Workflow

WhatsApp templates must be approved by Meta before use: 
Create Template (draft)
        |
        v
Submit to WhatsApp (pending)
        |
        v
Meta Reviews (24-48 hours)
        |
    +---+---+
    |       |
Approved  Rejected
    |       |
    v       v
Ready    Fix & Resubmit

​
Template Statuses

StatusDescription
draftCreated but not submitted
pendingSubmitted, awaiting Meta review
approvedReady to use
rejectedRejected by Meta (see reason)

​
Creating Templates

​
Via API

curl -X POST https://api.zavu.dev/v1/templates \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_shipped",
    "language": "en",
    "body": "Hi {{1}}, your order {{2}} has shipped and will arrive by {{3}}.",
    "whatsappCategory": "UTILITY",
    "variables": ["customer_name", "order_id", "delivery_date"]
  }'

​
Response

{
  "id": "tmpl_xyz789",
  "name": "order_shipped",
  "language": "en",
  "body": "Hi {{1}}, your order {{2}} has shipped...",
  "category": "UTILITY",
  "status": "draft",
  "variables": ["customer_name", "order_id", "delivery_date"],
  "createdAt": "2025-01-15T10:30:00Z"
}

​
Rich Template Components

WhatsApp templates can include rich components: Add a header with text, image, video, or document: 
{
  "headerType": "image",
  "headerContent": "https://example.com/logo.png"
}
Add a footer text: 
{
  "footer": "Reply STOP to unsubscribe"
}

​
Buttons

Add interactive buttons: 
{
  "buttons": [
    {
      "type": "quick_reply",
      "text": "Track Order"
    },
    {
      "type": "url",
      "text": "View Details",
      "url": "https://example.com/orders/{{1}}"
    }
  ]
}

​
Sending Template Messages

To send a template message, specify the template ID and variables: 
await client.messages.send({
  to: "+14155551234",
  messageType: "template",
  content: {
    templateId: "tmpl_abc123",
    templateVariables: {
      "1": "John",
      "2": "ORD-12345",
      "3": "January 20th"
    }
  }
});

​
Multi-Channel Templates

Templates can be configured for multiple channels: 
{
  "name": "order_confirmation",
  "channels": ["whatsapp", "sms", "email"],
  "body": "Hi {{1}}, your order {{2}} is confirmed!",
  "emailSubject": "Order {{2}} Confirmed",
  "emailHtmlBody": "<h1>Order Confirmed</h1><p>Hi {{1}}...</p>"
}
When smart routing selects a channel, the appropriate template format is used automatically.
Multi-channel templates must use the same variables across all channels for consistency.

​
Managing Templates

​
List Templates

curl https://api.zavu.dev/v1/templates \
  -H "Authorization: Bearer zv_live_xxx"

​
Get Template

curl https://api.zavu.dev/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer zv_live_xxx"

​
Delete Template

curl -X DELETE https://api.zavu.dev/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer zv_live_xxx"

​
Best Practices

Keep It Short

WhatsApp has character limits. Keep your templates concise and actionable.

Use UTILITY Category

For transactional messages, always use UTILITY to improve approval chances.

Test Before Launch

Create templates early in development. Approval can take 24-48 hours.

Handle Rejections

If rejected, review Meta’s guidelines, fix the issue, and resubmit.

​
Common Rejection Reasons

ReasonSolution
Promotional content in UTILITYChange category to MARKETING or remove promotional language
Missing variable examplesProvide clear example values for each variable
Inappropriate contentReview WhatsApp commerce policy
Poor grammar/spellingProofread and fix language errors

​
Next Steps

WhatsApp Templates

Deep dive into WhatsApp template features

Senders

Learn how templates work with senders