Templates Guide

Learn how to create and use message templates with the Zend.

What are Templates?

Templates are pre-approved message formats that allow you to:

Send consistent, branded messages
Required for WhatsApp business messages
Support dynamic content with variables
Include interactive buttons and media
Ensure compliance with messaging policies

Creating Templates

Basic Template Structure

POST /templates

{
  "name": "welcome_message",
  "description": "Welcome message for new customers",
  "category": "transactional",
  "variables": [
    {"name": "customer_name", "type": "text", "required": true},
    {"name": "website_url", "type": "url", "required": true}
  ],
  "channel_variants": [
    {
      "channel": "sms",
      "content": "Welcome {{customer_name}}! Visit us at {{website_url}}"
    },
    {
      "channel": "whatsapp",
      "content": "Welcome {{customer_name}}! 🎉\n\nThank you for joining our platform. We're excited to have you on board!\n\nGet started by exploring our features.",
      "header": "Welcome!",
      "footer": "We're here to help",
      "buttons": [
        {
          "type": "url",
          "text": "Get Started",
          "variable_name": "website_url"
        }
      ]
    }
  ]
}

Template Categories

Transactional Templates

For order confirmations, receipts, account updates:

{
  "name": "order_confirmation",
  "description": "Order confirmation with tracking details",
  "category": "transactional",
  "variables": [
    {"name": "customer_name", "type": "text", "required": true},
    {"name": "order_number", "type": "text", "required": true},
    {"name": "tracking_url", "type": "url", "required": true}
  ],
  "channel_variants": [
    {
      "channel": "whatsapp",
      "content": "Hi {{customer_name}}! ✅\n\nYour order #{{order_number}} has been confirmed and is being prepared for shipment.\n\nWe'll notify you when it ships!",
      "header": "Order Confirmed",
      "footer": "Thank you for your purchase",
      "buttons": [
        {
          "type": "url",
          "text": "Track Order",
          "variable_name": "tracking_url"
        }
      ]
    }
  ]
}

Authentication Templates

For OTP, password resets, verification:

{
  "name": "otp_verification",
  "description": "One-time password verification",
  "category": "authentication",
  "variables": [
    {"name": "code", "type": "text", "required": true},
    {"name": "verification_url", "type": "url", "required": true}
  ],
  "channel_variants": [
    {
      "channel": "whatsapp",
      "content": "Verification Code\n\nYour verification code is:\n{{code}}\n\nClick the button below to verify your account.",
      "header": "Verification Code",
      "footer": "Secure verification",
      "buttons": [
        {
          "type": "url",
          "text": "Verify Account",
          "variable_name": "verification_url"
        }
      ]
    }
  ]
}

Marketing Templates

For promotions, offers, announcements:

{
  "name": "special_offer",
  "description": "Special promotional offer",
  "category": "marketing",
  "variables": [
    {"name": "customer_name", "type": "text", "required": true},
    {"name": "offer_code", "type": "text", "required": true},
    {"name": "expiry_date", "type": "text", "required": true},
    {"name": "shop_url", "type": "url", "required": true}
  ],
  "channel_variants": [
    {
      "channel": "whatsapp",
      "content": "Hi {{customer_name}}! 🎉\n\nWe have a special offer just for you!\n\nUse code: {{offer_code}}\nValid until: {{expiry_date}}\n\nDon't miss out!",
      "header": "Special Offer",
      "footer": "Limited time only",
      "buttons": [
        {
          "type": "url",
          "text": "Shop Now",
          "variable_name": "shop_url"
        }
      ]
    }
  ]
}

Template Variables

Variable Types

Type	Description	Example
`text`	Plain text	Customer names, codes, numbers
`number`	Numeric values	Prices, quantities, IDs
`date`	Date values	Appointment dates, expiry dates
`url`	Web URLs	Tracking links, website URLs
`phone`	Phone numbers	Contact numbers

Variable Configuration

{
  "variables": [
    {
      "name": "customer_name",
      "type": "text",
      "required": true
    },
    {
      "name": "order_total",
      "type": "number",
      "required": true
    },
    {
      "name": "tracking_url",
      "type": "url",
      "required": true
    },
    {
      "name": "expiry_date",
      "type": "date",
      "required": false,
      "default_value": "30 days"
    }
  ]
}

Channel Variants

SMS Variant

Simple text-based messages:

{
  "channel": "sms",
  "content": "Hi {{customer_name}}, your order #{{order_number}} has been confirmed. Track at: {{tracking_url}}"
}

WhatsApp Variant

Rich media with buttons and formatting:

{
  "channel": "whatsapp",
  "content": "Hi {{customer_name}}! 🎉\n\nYour order #{{order_number}} has been confirmed and is being prepared for shipment.\n\nTrack your order: {{tracking_url}}",
  "header": "Order Confirmed",
  "footer": "Thank you for your purchase",
  "buttons": [
    {
      "type": "url",
      "text": "Track Order",
      "variable_name": "tracking_url"
    }
  ]
}

Button Configuration

URL Buttons

Link to external websites:

{
  "buttons": [
    {
      "type": "url",
      "text": "Visit Website",
      "variable_name": "website_url"
    }
  ]
}

Quick Reply Buttons

Simple response options:

{
  "buttons": [
    {
      "type": "quick_reply",
      "text": "Yes, I'm interested"
    },
    {
      "type": "quick_reply",
      "text": "No, thanks"
    }
  ]
}

Mixed Button Types

Combine URL and quick reply buttons:

{
  "buttons": [
    {
      "type": "url",
      "text": "Reschedule",
      "variable_name": "reschedule_url"
    },
    {
      "type": "quick_reply",
      "text": "Confirm"
    },
    {
      "type": "quick_reply",
      "text": "Cancel"
    }
  ]
}

Using Templates

Send with Template

{
  "to": "+233593152134",
  "body": "Welcome message",
  "template_id": "12345678912345",
  "template_params": {
    "customer_name": "John Doe",
    "website_url": "https://yourapp.com"
  },
  "preferred_channels": ["whatsapp", "sms"]
}

Bulk Template Usage

{
  "messages": [
    {
      "to": "+233593152134",
      "template_params": {
        "customer_name": "John",
        "order_number": "12345",
        "tracking_url": "https://track.com/12345"
      }
    },
    {
      "to": "+233593152135",
      "template_params": {
        "customer_name": "Sarah",
        "order_number": "12346",
        "tracking_url": "https://track.com/12346"
      }
    }
  ],
  "template_id": "12345678912345",
  "preferred_channels": ["whatsapp"]
}

Delivery Notification

{
  "name": "delivery_notification",
  "description": "Package delivery notification",
  "category": "transactional",
  "variables": [
    {"name": "customer_name", "type": "text", "required": true},
    {"name": "tracking_number", "type": "text", "required": true},
    {"name": "tracking_url", "type": "url", "required": true}
  ],
  "channel_variants": [
    {
      "channel": "whatsapp",
      "content": "📦 Package Delivered!\n\nHi {{customer_name}},\n\nYour package with tracking number {{tracking_number}} has been delivered successfully.\n\nThank you for choosing our service!",
      "header": "Package Delivered",
      "footer": "Thank you!",
      "buttons": [
        {
          "type": "url",
          "text": "Track Package",
          "variable_name": "tracking_url"
        }
      ]
    }
  ]
}

Common Template Errors

Missing Required Variables

{
  "statusCode": 400,
  "message": "Template rendering failed: Required variable 'customer_name' is missing",
  "error": "Bad Request"
}

Invalid Variable Type

{
  "statusCode": 400,
  "message": "Invalid value for variable 'tracking_url': Must be a valid URL",
  "error": "Bad Request"
}

Template Not Found

{
  "statusCode": 404,
  "message": "Template 'welcome_template' not found",
  "error": "Not Found"
}

Getting Started

Messaging

Templates