Templates

Pre-approved messages for WhatsApp Business outside the 24-hour window

Templates are pre-approved message formats required for contacting users outside the 24-hour conversation window. They must be submitted to Meta for approval before use.

Why Templates?

• Required by WhatsApp - Only way to message users outside 24-hour window
• Consistency - Ensure uniform messaging across your team
• Compliance - Meta reviews content for quality and policy compliance
• Analytics - Track performance by template

Quick Start: Send a Template Message

If you already have an approved template, here’s how to send it with variables:

TypeScript

const message = await zavu.messages.send({
  to: "[phone]",
  messageType: "template",
  content: {
    templateId: "tpl_abc123",
    templateVariables: {
      "1": "John",
      "2": "ORD-12345",
      "3": "January 20, 2025"
    }
  }
});

How Variables Work

A template can use one of two placeholder formats, and you pass values the same way for both:

• Positional: {{1}}, {{2}}, {{3}} — keyed by position.
• Named: {{customer_name}}, {{order_id}} — keyed by name.

Template body:  "Hi {{1}}, your order #{{2}} is confirmed. Delivery: {{3}}."
                     ^              ^                              ^
                     |              |                              |
Variables:      "1": "John"   "2": "ORD-12345"          "3": "January 20, 2025"

In both cases you provide the values through templateVariables. The keys match the placeholders in the template body — numbers for positional templates, names for named templates:

// Positional template
"templateVariables": { "1": "John", "2": "ORD-12345" }

// Named template
"templateVariables": { "customer_name": "John", "order_id": "ORD-12345" }

You must provide values for all variables defined in the template. Missing variables will cause the message to fail (#100 INVALID_PARAMETER from Meta).

Named vs Positional — which does my template use?

You normally don’t need to care: Zavu detects the format per template and builds the correct Meta payload. The distinction matters only when you decide what keys to use in templateVariables:

How the template was created	Format at Meta	Keys to use
Created in Zavu (POST /v1/templates)	Positional — Zavu converts {{name}} → {{1}} at submit time	Position numbers ("1", "2") or the original names
Imported from an existing WhatsApp Business Account	Whatever Meta has on file — named or positional	Match the placeholders in the template body

Fetch the template (GET /v1/templates/{id}) and read its body to see which placeholders it expects. If the body shows {{customer_name}}, use { "customer_name": "..." }; if it shows {{1}}, use { "1": "..." }.

Text Header Variables

A template can have a text header with its own variable, e.g. Invitación Boda {{novios}}. The header variable is independent from the body variables, but you pass its value through the same templateVariables object, keyed by the header placeholder’s name (or {{1}} for a positional header):

TypeScript

// Template header: "Invitación Boda {{novios}}"
// Template body:   "Estimado/a {{nombre}}, te corresponden {{pases}} boletos."
await zavu.messages.send({
  to: "[phone]",
  messageType: "template",
  content: {
    templateId: "tpl_wedding",
    templateVariables: {
      novios: "Jorge y Laura",   // header variable
      nombre: "Nestor Alvares",  // body variables
      pases: "4"
    }
  }
});

WhatsApp text headers allow at most one variable. Static text headers (no placeholder) need no value — Meta has the text baked into the approved template.

Full Workflow

Templates follow a 3-step process: Create -> Submit for Approval -> Send.

Step 1: Create a Template

TypeScript

const template = await zavu.templates.create({
  name: "order_confirmation",
  language: "en",
  body: "Hi {{1}}, your order #{{2}} has been confirmed! Estimated delivery: {{3}}.",
  whatsappCategory: "UTILITY",
  variables: ["customer_name", "order_id", "delivery_date"]
});

console.log(template.id);     // "tpl_abc123"
console.log(template.status); // "draft"

The variables array is optional and purely for documentation - it helps you remember what each position represents.

Step 2: Submit for Approval

Templates start in draft status. You need to explicitly submit them to Meta for review:

TypeScript

const submitted = await zavu.templates.submit("tpl_abc123", {
  senderId: "sender_12345",
  category: "UTILITY"
});

console.log(submitted.status); // "pending"

The senderId must be a sender with a WhatsApp Business Account connected. The template is submitted to Meta through that WABA.

Step 3: Check Approval Status

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

{
  "id": "tpl_abc123",
  "name": "order_confirmation",
  "status": "approved",
  "category": "UTILITY",
  "body": "Hi {{1}}, your order #{{2}} has been confirmed! Estimated delivery: {{3}}.",
  "variables": ["customer_name", "order_id", "delivery_date"]
}

Status	Description
draft	Created but not yet submitted to Meta
pending	Submitted, awaiting Meta review
approved	Ready to use
rejected	Not approved - check rejection reason

Only approved templates can be used to send messages. Attempting to use draft, pending, or rejected templates will fail.

Step 4: Send the Template

Once approved, send it using the positional variables (see Quick Start above).

Template Categories

Category	Use Case	Approval Speed
UTILITY	Order updates, shipping, account alerts	Fast (hours)
MARKETING	Promotions, offers, newsletters	Slower (days)
AUTHENTICATION	OTPs, verification codes	Fast (hours)

Choose the category that best matches your use case. Miscategorization can lead to rejection.

Templates with Buttons

Add call-to-action or quick reply buttons:

curl -X POST https://api.zavu.dev/v1/templates \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_delivered",
    "language": "en",
    "body": "Hi {{1}}, your order has been delivered!",
    "whatsappCategory": "UTILITY",
    "variables": ["customer_name"],
    "buttons": [
      {
        "type": "url",
        "text": "Track Order",
        "url": "https://example.com/track/{{1}}"
      },
      {
        "type": "quick_reply",
        "text": "Rate Delivery"
      }
    ]
  }'

Button Types

Type	Description	Max
quick_reply	User response button	3 buttons
url	Opens a URL (can include variables)	-
phone	Initiates a phone call	-
otp	Copy code / one-tap autofill for authentication	-

Sending Templates with Dynamic URL Buttons

When a template has a URL button with a {{1}} placeholder, pass the substitution under templateButtonVariables keyed by the button’s position in the template’s buttons array.

templateVariables is for body placeholders. templateButtonVariables is for buttons. They use different keys:

• templateVariables keys → position of the placeholder in the body text ("1", "2", …).
• templateButtonVariables keys → index of the button in the buttons array ("0", "1", "2").

WhatsApp URL buttons only accept {{1}} (positional, numeric, no whitespace, no name). Even though body placeholders may use named parameters like {{name}}, URL buttons do not. Anything else ({{token}}, {{ 1 }}, {{user.id}}, etc.) is approved by Meta as literal text in the URL — there is no way to substitute it later.

If your template was approved with a non-{{1}} placeholder in a URL button, you must recreate the template with {{1}} and resubmit it for approval. Zavu now returns 400 invalid_request instead of silently delivering broken URLs like https://...%7B%7Bvariable%7D%7D.

Example. Suppose your approved template looks like this:

{
  "id": "tpl_discipline_report",
  "body": "Hi {{1}}, your child received a {{2}}.",
  "buttons": [
    {
      "type": "url",
      "text": "View report",
      "url": "https://reporte.link/{{1}}"
    }
  ]
}

Send it like this:

TypeScript

await zavu.messages.send({
  to: "[phone]",
  messageType: "template",
  content: {
    templateId: "tpl_discipline_report",
    templateVariables: {
      "1": "Marco Ordaz",
      "2": "report for inappropriate behavior"
    },
    templateButtonVariables: {
      "0": "abc-report-token"
    }
  }
});

The recipient receives a button that opens https://reporte.link/abc-report-token.

Multiple buttons

For templates with several buttons, supply one entry per dynamic button. Static URL buttons (no {{1}}) and quick_reply buttons are not included in templateButtonVariables.

{
  "buttons": [
    { "type": "url", "text": "View order", "url": "https://shop.example.com/orders/{{1}}" },
    { "type": "quick_reply", "text": "Track" },
    { "type": "url", "text": "Help", "url": "https://help.example.com/" }
  ]
}

{
  "templateButtonVariables": {
    "0": "ORD-12345"
  }
}

Index 1 (quick reply) and index 2 (static URL) are skipped.

Validation rules

Rule	Behavior
URL has {{1}} and templateButtonVariables[index] provided	✅ delivered with substitution
URL has {{1}} and templateButtonVariables[index] missing	❌ 400 invalid_request: Missing URL button parameter at index N
URL has {{name}}, {{ 1 }}, {{token}}, etc.	❌ 400 invalid_request: ... WhatsApp treats it as literal text. Recreate the template with "{{1}}" and resubmit it for approval.
URL has more than one placeholder (e.g. /{{1}}/{{2}})	❌ 400 invalid_request: at most one positional variable
URL has no placeholder (static link)	✅ ignored — do not include the index in templateButtonVariables

Authentication Templates (OTP)

For verification codes, use AUTHENTICATION category with OTP buttons:

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

Send the OTP:

curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[phone]",
    "messageType": "template",
    "content": {
      "templateId": "tpl_otp123",
      "templateVariables": {
        "1": "482910"
      }
    }
  }'

See the OTP Templates guide for more details.

Managing Templates

List Templates

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

Delete Template

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

Best Practices

Naming Conventions

Use descriptive, lowercase names with underscores:

order_confirmation
shipping_update
password_reset
appointment_reminder
promotional_offer

Content Guidelines

Do:

• Use clear, concise language
• Include dynamic variables for personalization
• Provide value to the recipient
• Test with real data before production use

Don’t:

• Use placeholder text like “[insert name]”
• Include excessive capitalization or punctuation
• Send promotional content without consent
• Use misleading or clickbait content

Common Rejection Reasons

Reason	Solution
Variable syntax error	Use {{1}}, {{2}} positional format
Category mismatch	Choose correct category for content
Promotional in UTILITY	Use MARKETING category for promotions
Missing opt-out	Include unsubscribe option for marketing
Policy violation	Review Meta’s commerce and messaging policies

Testing Templates

Test with your own phone number before sending to customers:

curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer zv_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+your_phone_number",
    "messageType": "template",
    "content": {
      "templateId": "tpl_abc123",
      "templateVariables": {
        "1": "Test User",
        "2": "TEST-001",
        "3": "Tomorrow"
      }
    }
  }'

Use test mode API keys (zv_test_xxx) during development to avoid charges.