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

{
  "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:

Channel	Identifier	Smart Routing	Fallback	Setup Guide
SMS	Phone number (E.164)	Yes	Yes	SMS Guide
WhatsApp	Phone number (E.164)	Yes	Yes	WhatsApp Guide
Email	Email address	No	No	Email Guide
Telegram	Telegram chat ID	No	No	Telegram Guide
Instagram	Instagram-scoped ID	No	No	—
Voice	Phone number (E.164)	No	No	Sending Messages

Smart routing and automatic fallback only apply to SMS and WhatsApp. Email, Telegram, Instagram, and Voice are standalone channels that must be explicitly specified with the channel parameter.

Default Sender

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

# 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:

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.

Smart routing only applies to outbound messages. When replying to an inbound message, Zavu always responds on the same channel the contact used.

When Smart Routing Applies

Message Type	Routing Behavior
Outbound (you initiate)	Smart routing selects optimal channel
Inbound reply (direct response)	Always use the contact’s channel

How It Works

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

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:

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

Cost Optimization

Channel	Approximate Cost
WhatsApp	~$0.01/message
SMS	~$0.05/message

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.

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

If the 24-hour window is closed and you don’t have a template configured, the smart router will automatically select SMS instead of failing.

Channel Metrics

Zavu tracks delivery metrics for each contact and channel:

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

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

Rule	Description
Max 2 attempts	Each message is tried on at most 2 channels
5-second delay	Wait 5 seconds before retry to avoid race conditions
No duplicate channels	Never retry on a channel that already failed
Sender must support both	Fallback only works if sender has both channels configured

Enabling/Disabling Fallback

Fallback is enabled by default. You can disable it per message by setting fallbackEnabled: false:

{
  "id": "msg_abc123",
  "status": "delivered",
  "channel": "sms",
  "fallbackEnabled": true
}

Standalone Channels

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

Channel	Key Requirement	Docs
Email	KYC verification + domain setup	Email Setup
Telegram	Bot token via BotFather	Telegram Setup
Instagram	Instagram Business Account	—
Voice	Phone number with voice capability	Sending Messages

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

Channel	Rate Limit	Level
SMS	10 messages/second	Global
Email	14 messages/second	Global
WhatsApp	60 messages/second	Per WABA

Round-Robin Fairness

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

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.

Messages are never dropped due to rate limiting. They’re queued and sent at the next available slot.

Managing Senders

List Senders

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

Create Sender

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

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

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):

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

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:

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

Available Webhook Events

Event	Description
`message.queued`	Message created and queued for sending
`message.sent`	Message accepted by the provider
`message.delivered`	Message delivered to recipient
`message.failed`	Message delivery failed
`message.inbound`	Contact sent you a message
`message.unsupported`	Received an unsupported message type
`conversation.new`	First message from a new contact
`template.status_changed`	WhatsApp template approval status changed

For webhook payload structure and signature verification, see the Webhooks guide and Webhook Security.

Best Practices

Configure Multiple Channels

Set up both SMS and WhatsApp on your sender to enable smart routing and automatic fallback.

Use Templates for Outreach

When initiating conversations, use WhatsApp templates to avoid 24-hour window issues.

Monitor Metrics

Check your contact metrics to understand channel performance in your region.

Set Allowed Destinations

Restrict senders to specific countries to control costs and compliance.

Next Steps

Adding Channels

Connect SMS, WhatsApp, Email, Telegram, and more to your sender

Phone Numbers

Purchase and manage phone numbers for SMS and voice

Templates

Create WhatsApp templates for outbound messaging

Smart Routing Guide

Deep dive into routing configuration

Getting Started

Concepts

Guides

​Senders

​What is a Sender?

​Channels

​Default Sender

​Smart Routing

​When Smart Routing Applies

​How It Works

​Channel Selection Algorithm

​Cost Optimization

​WhatsApp 24-Hour Window

​Channel Metrics

​Automatic Fallback

​Fallback Flow

​Fallback Rules

​Enabling/Disabling Fallback

​Standalone Channels

​Rate Limiting

​Limits by Channel

​Round-Robin Fairness

​Managing Senders

​List Senders

​Create Sender

​Update Sender

​Webhook Configuration

​Create Sender with Webhook

​Update Webhook

​Regenerate Webhook Secret

​Available Webhook Events

​Best Practices

Configure Multiple Channels

Use Templates for Outreach

Monitor Metrics

Set Allowed Destinations

​Next Steps

Adding Channels

Phone Numbers

Templates

Smart Routing Guide

Senders

What is a Sender?

Channels

Default Sender

Smart Routing

When Smart Routing Applies

How It Works

Channel Selection Algorithm

Cost Optimization

WhatsApp 24-Hour Window

Channel Metrics

Automatic Fallback

Fallback Flow

Fallback Rules

Enabling/Disabling Fallback

Standalone Channels

Rate Limiting

Limits by Channel

Round-Robin Fairness

Managing Senders

List Senders

Create Sender

Update Sender

Webhook Configuration

Create Sender with Webhook

Update Webhook

Regenerate Webhook Secret

Available Webhook Events

Best Practices

Next Steps