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:

WhatsApp Compliance: Meta requires businesses to use approved templates when initiating conversations outside the 24-hour window
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

Field	Description
`name`	Unique identifier (lowercase, underscores)
`language`	Language code (e.g., “en”, “es”, “pt”)
`body`	Message text with variable placeholders
`category`	WhatsApp category (see below)
`variables`	List of variable names for documentation
`status`	Approval 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:

Category	Use Case	Examples
UTILITY	Transactional messages	Order confirmations, shipping updates, appointment reminders
MARKETING	Promotional content	Sales, offers, newsletters
AUTHENTICATION	Verification codes	OTPs, login codes, 2FA

Marketing templates have stricter approval requirements and may have different pricing. Use UTILITY for transactional messages.

Authentication Templates

Authentication templates are used for sending verification codes (OTPs) to users. These templates have special requirements and behavior.

Requirements

Meta requires your WhatsApp Business Account to meet these criteria before you can create AUTHENTICATION templates:

Business Verification: Your business must be verified by Meta
Conversation History: At least 2,000 business-initiated conversations in the last 30 days

If your account doesn’t meet these requirements, AUTHENTICATION templates will fail with a permission error.

How Authentication Templates Work

Unlike regular templates, authentication templates have a pre-defined message format controlled by Meta. When you create an authentication template:

The message body is automatically generated by Meta
The format is: {{1}} is your verification code.
You cannot customize the body text

OTP Button Types

Authentication templates support two types of OTP buttons:

Button Type	Description	Use Case
COPY_CODE	Shows a “Copy Code” button	User manually copies and pastes the code
ONE_TAP	Enables Android autofill	Automatic code entry on Android devices

ONE_TAP Button Requirements

For ONE_TAP buttons (Android autofill), you must provide:

{
  "buttons": [{
    "type": "otp",
    "text": "Autofill",
    "otpType": "ONE_TAP",
    "packageName": "com.yourapp.package",
    "signatureHash": "your_app_signature_hash"
  }]
}

Field	Description
`packageName`	Your Android app’s package name
`signatureHash`	Your Android app’s signature hash for SMS verification

Optional Security Features

Authentication templates can include:

Feature	Description
`addSecurityRecommendation`	Adds “Do not share this code with anyone” disclaimer
`codeExpirationMinutes`	Shows expiration time (1-90 minutes) in footer

Creating an Authentication Template

curl -X POST https://api.zavu.dev/v1/templates \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "verification_code",
    "language": "en",
    "body": "",
    "whatsappCategory": "AUTHENTICATION",
    "buttons": [{
      "type": "otp",
      "text": "Copy Code",
      "otpType": "COPY_CODE"
    }],
    "addSecurityRecommendation": true,
    "codeExpirationMinutes": 10
  }'

The body field should be empty or omitted for authentication templates. Meta will automatically generate the message body.

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

Status	Description
`draft`	Created but not submitted
`pending`	Submitted, awaiting Meta review
`approved`	Ready to use
`rejected`	Rejected 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

Reason	Solution
Promotional content in UTILITY	Change category to MARKETING or remove promotional language
Missing variable examples	Provide clear example values for each variable
Inappropriate content	Review WhatsApp commerce policy
Poor grammar/spelling	Proofread and fix language errors

Getting Started

Concepts

Guides

​Templates

​Why Templates?

​Template Structure

​Fields

​Template Variables

​Numbered Variables (WhatsApp Native)

​Named Variables

​WhatsApp Categories

​Authentication Templates

​Requirements

​How Authentication Templates Work

​OTP Button Types

​ONE_TAP Button Requirements

​Optional Security Features

​Creating an Authentication Template

​WhatsApp Approval Workflow

​Template Statuses

​Creating Templates

​Via API

​Response

​Rich Template Components

​Header

​Footer

​Buttons

​Sending Template Messages

​Multi-Channel Templates

​Managing Templates

​List Templates

​Get Template

​Delete Template

​Best Practices

Keep It Short

Use UTILITY Category

Test Before Launch

Handle Rejections

​Common Rejection Reasons

​Next Steps

WhatsApp Templates

Senders

Templates

Why Templates?

Template Structure

Fields

Template Variables

Numbered Variables (WhatsApp Native)

Named Variables

WhatsApp Categories

Authentication Templates

Requirements

How Authentication Templates Work

OTP Button Types

ONE_TAP Button Requirements

Optional Security Features

Creating an Authentication Template

WhatsApp Approval Workflow

Template Statuses

Creating Templates

Via API

Response

Rich Template Components

Header

Footer

Buttons

Sending Template Messages

Multi-Channel Templates

Managing Templates

List Templates

Get Template

Delete Template

Best Practices

Common Rejection Reasons

Next Steps