WhatsApp templates

Business-initiated WhatsApp messages must render from an approved template. A template defines the message content and its variables once; each send fills those variables through template_params.

Design and manage templates in Templates, then reference a template by its template_id when you send.

POST/messages

Using an approved template

To send with a template, reference its template_id and pass values for every required variable in template_params:

curl -X POST https://api.tryzend.com/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+233593152134",
    "body": "Your verification code is ready",
    "preferred_channels": ["whatsapp"],
    "template_id": "6884c5d09c14b2b164500d58",
    "template_params": {
      "code": "123456",
      "verification_url": "https://yourapp.com/verify?code=123456"
    }
  }'

Request fields

template_idstringrequired
ID of the approved template to render.
template_paramsobjectrequired
Key-value pairs mapping each template variable to its value. Missing required variables cause the send to fail.

Template structure

A template declares its variables and one or more channel variants. The WhatsApp variant holds the content, optional header and footer, and any buttons:

{
  "name": "otp_verification",
  "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"
        }
      ]
    }
  ]
}

Variables are referenced in content with {{variable_name}} and filled at send time by template_params. Each variable declares a type (such as text or url) and whether it is required.

Categories & approval

Every template declares a category that describes its purpose:

{
  "name": "order_confirmation",
  "description": "Order confirmation with tracking",
  "category": "transactional",
  "variables": [
    {"name": "customer_name", "type": "text", "required": true},
    {"name": "order_number", "type": "text", "required": true}
  ]
}

Common categories include transactional and notification. WhatsApp must approve a template before it can be used for business-initiated messages. Sending with an unapproved template returns a 400:

{
  "statusCode": 400,
  "message": "Template 'marketing_promo' is not approved by WhatsApp. Please use an approved template.",
  "error": "Bad Request"
}

Note

Create templates, declare their variables, and track approval status in Templates.
PreviousOverviewNext Interactive & media