WhatsApp delivery & fallback

Track WhatsApp message delivery, fall back to SMS when WhatsApp can't reach a recipient, and receive real-time status updates through webhooks. This page also lists the common WhatsApp errors you may encounter.

POST/messages

Fallback to SMS

List multiple channels in preferred_channels and set fallback_enabled to have Zend try WhatsApp first and fall back to SMS if delivery fails:

curl -X POST https://api.tryzend.com/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+233593152134",
    "body": "Important notification: Your order has been shipped!",
    "preferred_channels": ["whatsapp", "sms"],
    "template_id": "12345678912345",
    "template_params": {
      "order_number": "ORD-2024-001",
      "tracking_url": "https://track.com/ORD-2024-001"
    },
    "fallback_enabled": true
  }'

Request fields

preferred_channelsstring[]required
Channels to attempt in order. ["whatsapp", "sms"] tries WhatsApp first, then SMS.
fallback_enabledboolean
When true, Zend falls back to the next channel if the first fails to deliver.

Delivery & read status

Check the status of any message by its ID:

curl https://api.tryzend.com/messages/6884da240f0e633b7b979bff \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "id": "6884da240f0e633b7b979bff",
  "status": "delivered",
  "channel_used": "whatsapp",
  "to": "+233593152134",
  "body": "Your verification code is: 123456",
  "total_cost": 0.008,
  "delivery_attempts": [
    {
      "channel": "whatsapp",
      "status": "delivered",
      "attempted_at": "2024-01-15T10:30:00Z",
      "cost": 0.008
    }
  ],
  "created_at": "2024-01-15T10:29:55Z",
  "sent_at": "2024-01-15T10:30:00Z",
  "delivered_at": "2024-01-15T10:30:05Z"
}

The delivery_attempts array records each channel Zend tried, which is where you'll see a WhatsApp attempt followed by an SMS attempt when fallback occurs.

Webhooks

Add a webhook_url to a send to receive real-time delivery status updates:

{
  "to": "+233593152134",
  "body": "Your order has been shipped!",
  "preferred_channels": ["whatsapp"],
  "template_id": "12345678912345",
  "template_params": {
    "order_number": "ORD-2024-001"
  },
  "webhook_url": "https://yourapp.com/webhooks/message-status"
}

Webhook payload:

{
  "message_id": "6884da240f0e633b7b979bff",
  "status": "delivered",
  "channel": "whatsapp",
  "recipient": "+233593152134",
  "timestamp": "2024-01-15T10:30:05Z",
  "cost": 0.008
}

Common errors

ErrorStatusMessage
Template required400WhatsApp requires template messages for business-initiated conversations. Please provide a template_id and template_params.
Invalid template400Template rendering failed: Required variable 'customer_name' is missing.
Template not approved400Template 'marketing_promo' is not approved by WhatsApp. Please use an approved template.
Number not on WhatsApp400Recipient +233593152134 is not available on WhatsApp.

Note

When a recipient isn't available on WhatsApp, enable SMS fallback so the message still reaches them.

Example error response body:

{
  "statusCode": 400,
  "message": "WhatsApp requires template messages for business-initiated conversations. Please provide a template_id and template_params.",
  "error": "Bad Request"
}
PreviousInteractive & mediaNext Overview