Variables & variants

Variables make templates dynamic, and channel variants let a single template render differently on SMS versus WhatsApp. This page covers variable types and substitution, per-channel variants, and button configuration. For creating templates and category examples, start with the Templates overview.

Template variables

Variables are placeholders in your template content, written as {{variable_name}}. When you send, Zend substitutes each placeholder with the value you supply in template_params.

Welcome {{customer_name}}! Visit us at {{website_url}}

Variable types

TypeDescriptionExample
textPlain textCustomer names, codes, numbers
numberNumeric valuesPrices, quantities, IDs
dateDate valuesAppointment dates, expiry dates
urlWeb URLsTracking links, website URLs
phonePhone numbersContact numbers

Variable configuration

Declare each variable with a name, a type, and whether it's required. Optional variables can specify a default_value.

{
  "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"
    }
  ]
}

Variable fields

namestringrequired
The variable name, referenced in content as {{name}} and supplied in template_params.
typestringrequired
Value type. One of text, number, date, url, or phone. Supplied values are validated against this type.
requiredbooleanrequired
Whether a value must be supplied when sending.
default_valuestring
Value used when the variable is optional and no value is supplied.

Substitution at send time

Provide values in template_params, keyed by variable name:

{
  "template_params": {
    "customer_name": "John Doe",
    "order_total": 149.99,
    "tracking_url": "https://track.com/12345"
  }
}

Note

Every required variable must be supplied, and each value must match its declared type. Missing or mistyped values return a 400 — see common template errors.

Channel variants

A template can define one variant per channel. Zend renders the variant that matches the channel it sends over, so the same template can be plain text on SMS and rich media on WhatsApp.

SMS variant

Simple text-based messages — content only.

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

WhatsApp variant

Rich media with header, footer, formatting, and buttons.

{
  "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"
    }
  ]
}

Variant fields

channelstringrequired
The channel this variant renders for. sms or whatsapp.
contentstringrequired
The message body. Use {{variable_name}} placeholders for dynamic content.
headerstring
Optional heading shown above the content (WhatsApp).
footerstring
Optional footer shown below the content (WhatsApp).
buttonsobject[]
Interactive buttons (WhatsApp). See button configuration.

Button configuration

Buttons add interactive elements to WhatsApp variants. Each button has a type and display text. URL buttons resolve their link from a variable.

URL buttons

Link to external websites. variable_name points at the variable that holds the URL.

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

Quick reply buttons

Simple response options the recipient can tap.

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

Mixed button types

Combine URL and quick reply buttons in a single variant.

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

Button fields

typestringrequired
Button type. url for links, or quick_reply for tappable responses.
textstringrequired
The label displayed on the button.
variable_namestring
For url buttons, the variable holding the destination URL.

Next steps

PreviousOverviewNext Overview