Senders — Smart Routing & Fallback

Senders

A Sender is a messaging profile that represents "who" is sending the message. Senders can be configured with multiple channels — SMS, WhatsApp, Email, Telegram, Instagram, and Voice — and Zavu intelligently routes messages through them.

What is a Sender?

Think of a sender as your messaging identity. It contains:

• Phone number — used for SMS, WhatsApp, and Voice messaging
• WhatsApp Business Account — for WhatsApp messaging (rich media, templates, interactive messages)
• Email domain — for transactional email via Amazon SES
• Telegram bot — for Telegram messaging
• Instagram Business Account — for Instagram direct messaging
• Webhooks — real-time notifications for inbound messages and delivery updates
• Allowed destinations — countries you can send to

Example SenderCopy
{
  "id": "sender_12345",
  "name": "Primary Sender",
  "phoneNumber": "+13125551212",
  "isDefault": true,
  "webhook": {
    "url": "https://your-app.com/webhooks",
    "events": ["message.inbound", "message.delivered"],
    "active": true
  },
  "whatsapp": {
    "phoneNumberId": "123456789",
    "displayPhoneNumber": "+13125551212"
  },
  "emailReceivingEnabled": false,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}

Channels

Zavu supports 6 messaging channels. Each has different requirements and routing behavior:

Default Sender

Every project has a default sender. When you send a message without specifying a sender, Zavu uses the default.

terminalCopy
# Uses default sender automatically
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer zv_live_xxx" \
  -d '{"to": "+14155551234", "text": "Hello!"}'

To use a specific sender, include the Zavu-Sender header:

terminalCopy
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Zavu-Sender: sender_67890" \
  -d '{"to": "+14155551234", "text": "Hello!"}'

Smart Routing

Zavu's smart routing system automatically selects the optimal channel for each message based on cost, deliverability, and contact history. Smart routing applies only to SMS and WhatsApp.

When Smart Routing Applies

How It Works

For outbound messages, the router checks if the contact has previously messaged you. If they have, this affects channel availability:

CodeCopy
Has contact messaged via WhatsApp in last 24h?
      |
   +--+--+
   |     |
  Yes   No
   |     |
   v     v
WhatsApp    WhatsApp only
available   with template
(preferred)

Since WhatsApp is cheaper than SMS, the router prefers WhatsApp when the 24-hour window is open. This means contacts who have messaged you before will typically receive messages via WhatsApp.

Channel Selection Algorithm

The router evaluates channels in this order:

1. Filter viable channels: Remove channels that can't deliver (e.g., WhatsApp without open window)
2. Sort by cost: Cheapest channels first
3. Check success rate: Channel must have at least 80% success rate (or fewer than 3 attempts for exploration)
4. Select best option: First channel meeting all criteria

Cost Optimization

Smart routing can reduce messaging costs by up to 80% by preferring WhatsApp when available.

WhatsApp 24-Hour Window

WhatsApp has a strict rule: you can only send free-form messages within 24 hours of the last message received from the contact.

CodeCopy
Contact sends message ... 24-hour window opens
      |
Within 24h: Send any message type
      |
After 24h: Only template messages allowed

Channel Metrics

Zavu tracks delivery metrics for each contact and channel:

JSONCopy
{
  "channelMetrics": {
    "sms": {
      "successCount": 45,
      "failureCount": 2,
      "avgDeliveryTimeMs": 3200,
      "lastSuccessAt": "2025-01-15T10:30:00Z"
    },
    "whatsapp": {
      "successCount": 120,
      "failureCount": 1,
      "avgDeliveryTimeMs": 1100,
      "lastSuccessAt": "2025-01-15T14:22:00Z"
    }
  }
}

The router uses these metrics to:

• Avoid channels with low success rates (below 80%)
• Prefer faster channels when speed matters
• Explore new channels (first 3 attempts get a chance regardless of stats)

Automatic Fallback

When a message fails on one channel, Zavu automatically retries on an alternate channel. Fallback works between SMS and WhatsApp only.

Fallback Flow

CodeCopy
Send via WhatsApp
      |
      v
  Failed?
      |
   +--+--+
   |     |
  No    Yes
   |     |
   v     v
Done   Wait 5s
         |
         v
   Retry via SMS
         |
         v
     Success?
         |
      +--+--+
      |     |
     Yes   No
      |     |
      v     v
   Done   Mark Failed

Fallback Rules

Enabling/Disabling Fallback

Whether fallback runs depends on how you choose the channel:

Choosing a channel explicitly means Zavu does not switch it for you, because an SMS is billed from your balance. To keep the SMS safety net on an explicit WhatsApp send, ask for it:

JSONCopy
{
  "to": "+14155551234",
  "channel": "whatsapp",
  "text": "Your order has shipped.",
  "fallbackEnabled": true
}

Only text and template messages fall back. Media, buttons, lists and other WhatsApp-only types never do.

Standalone Channels

Email, Telegram, Instagram, and Voice operate independently from smart routing. You must explicitly specify the channel parameter when using them.

These channels don't participate in smart routing or automatic fallback because they use different recipient identifiers and have different delivery semantics than SMS/WhatsApp.

Rate Limiting

Zavu implements fair rate limiting to ensure reliable delivery for all users.

Limits by Channel

Round-Robin Fairness

When multiple projects are sending messages, Zavu uses round-robin scheduling to ensure fairness:

CodeCopy
Without round-robin:
Project A: 10 messages = A1, A2, A3... A10 (1 second)
Project B: 1 message  = B1 waits 1 second

With round-robin:
A1 (0ms), B1 (100ms), A2 (200ms), A3 (300ms)...
B1 only waits 100ms instead of 1 second

This prevents high-volume senders from blocking smaller senders.

Managing Senders

List Senders

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

Create Sender

terminalCopy
curl -X POST https://api.zavu.dev/v1/senders \
  -H "Authorization: Bearer zv_live_xxx" \
  -d '{
    "name": "Marketing Sender",
    "phoneNumber": "+13125559999",
    "setAsDefault": false
  }'

Update Sender

terminalCopy
curl -X PATCH https://api.zavu.dev/v1/senders/sender_12345 \
  -H "Authorization: Bearer zv_live_xxx" \
  -d '{
    "name": "Updated Name",
    "setAsDefault": true
  }'

Webhook Configuration

Each sender can have one webhook configured to receive real-time notifications for events like incoming messages and delivery updates. See the Webhooks guide for payload details and security.

Create Sender with Webhook

terminalCopy
curl -X POST https://api.zavu.dev/v1/senders \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support",
    "phoneNumber": "+15551234567",
    "webhookUrl": "https://your-app.com/webhooks",
    "webhookEvents": ["message.inbound", "message.delivered", "message.failed"]
  }'

The response includes the webhook secret (only shown once):

JSONCopy
{
  "id": "sender_12345",
  "name": "Support",
  "webhook": {
    "url": "https://your-app.com/webhooks",
    "events": ["message.inbound", "message.delivered", "message.failed"],
    "secret": "whsec_abc123...",
    "active": true
  }
}

Update Webhook

terminalCopy
curl -X PATCH https://api.zavu.dev/v1/senders/sender_12345 \
  -H "Authorization: Bearer zv_live_xxx" \
  -d '{
    "webhookUrl": "https://new-url.com/webhooks",
    "webhookEvents": ["message.inbound"],
    "webhookActive": false
  }'

Regenerate Webhook Secret

If your webhook secret is compromised:

terminalCopy
curl -X POST https://api.zavu.dev/v1/senders/sender_12345/webhook/secret \
  -H "Authorization: Bearer zv_live_xxx"

Available Webhook Events

Best Practices

Next Steps

API Reference

Manage senders programmatically:

• List senders — fetch all senders for your project
• Create a sender — register a new messaging profile
• Get a sender — retrieve sender details by ID
• Update a sender — change profile, channels, or webhooks
• Delete a sender — remove a sender from your project