Understanding Zavu’s core concepts will help you build more effective messaging applications.
Channels
A channel is a communication medium through which messages are sent and received. Zavu supports multiple channels:
| Channel | Description | Best For |
|---|
| SMS | Traditional text messages | Universal reach, critical alerts |
| WhatsApp | WhatsApp Business API | Rich media, high engagement |
| Telegram | Telegram Bot API | Cost-effective, tech-savvy users |
Messages
Messages in Zavu are categorized by their direction:
Outbound Messages
Messages initiated by your application to users.
- Marketing campaigns
- Transactional notifications (order confirmations, OTPs)
- Proactive alerts
- Appointment reminders
Smart Routing applies to outbound messages, automatically selecting the best channel.
Inbound Messages
Messages received from users.
- Customer inquiries
- Support requests
- Replies to your messages
- User-initiated conversations
Inbound messages always use the channel the customer chose. When replying, you should use the same channel to maintain conversation context.
Use the message.inbound webhook event to receive real-time notifications when users message you.
Smart Routing
Smart Routing is Zavu’s ML-powered system that automatically selects the optimal channel for each outbound message.
How It Works
- Filters viable channels - Considers WhatsApp 24-hour window rules and sender configurations
- Sorts by cost - Orders channels from cheapest to most expensive
- Checks success rates - Selects the cheapest channel with 80%+ delivery success
- Falls back intelligently - If no channel meets the threshold, uses the one with best historical success
Channel Costs
| Channel | Cost per message |
|---|
| Telegram | $0.005 |
| WhatsApp | $0.01 |
| SMS | $0.05 |
Exploration vs Exploitation
Smart Routing uses an epsilon-greedy strategy:
- Exploration: For contacts with fewer than 3 attempts on a channel, it tries that channel to gather data
- Exploitation: For contacts with sufficient data, it uses the cheapest channel that meets the success threshold
This ensures the system continuously learns while optimizing for cost and delivery.
Fallback
Fallback is automatic retry on a different channel when a message fails to deliver.
Message sent via WhatsApp → Delivery failed → Retry via SMS → Delivered
How It Works
- You send a message via the selected channel
- If delivery fails (unreachable, blocked, etc.), Zavu automatically tries the next available channel
- This continues until the message is delivered or all channels are exhausted
Configuration
Fallback is configured per Sender. When creating a Sender with multiple channels, fallback is enabled by default.
const sender = await zavu.senders.create({
name: "Notifications",
routingPolicy: "smart",
channels: {
whatsapp: { phoneNumber: "+1234567890" },
sms: { phoneNumber: "+1234567890" } // Fallback channel
}
});
Configure SMS as a fallback channel for critical messages. SMS has the highest reach but is also the most expensive.
WhatsApp 24-Hour Window
WhatsApp has a strict messaging policy: you can only send free-form text within 24 hours of the last message received from the customer.
Window States
| State | Condition | Allowed Messages |
|---|
| Open | Customer messaged within 24h | Free-form text or templates |
| Closed | No customer message in 24h | Templates only |
Impact on Routing
Smart Routing automatically considers the window state:
- Window open → WhatsApp is viable for any message
- Window closed → WhatsApp is only viable if you’re sending a template
Best Practices
- Use templates for cold outreach - If contacting customers who haven’t messaged recently
- Respond quickly - Reply within 24 hours to keep the window open
- Re-engage with templates - Use approved templates to restart conversations
Senders
A Sender is a configuration that defines how messages are sent. It includes:
- Name - Identifier for the sender (e.g., “Marketing”, “Support”)
- Routing Policy - How channels are selected (
smart or manual)
- Channels - Phone numbers configured for each channel
Multi-Channel Senders
A single Sender can be configured with multiple channels:
const sender = await zavu.senders.create({
name: "Customer Support",
routingPolicy: "smart",
channels: {
sms: { phoneNumber: "+1234567890" },
whatsapp: { phoneNumber: "+1234567890" },
telegram: { botToken: "123456:ABC..." }
}
});
Channel Metrics
For each contact, Zavu tracks per-channel delivery metrics:
| Metric | Description |
|---|
| Success Count | Delivered messages |
| Failure Count | Failed deliveries |
| Total Attempts | All delivery attempts |
| Avg Delivery Time | Time from send to delivery |
| Last Success | Timestamp of last successful delivery |
Last Inbound Tracking
Zavu tracks the last inbound message timestamp per channel for each contact. This is used to determine WhatsApp window state:
lastInboundAt: {
sms: 1705312200000,
whatsapp: 1705398600000, // Recent - window open
telegram: null
}
Templates
Templates are pre-approved message formats required for certain channels and use cases.
WhatsApp Templates
WhatsApp requires templates for:
- Messages outside the 24-hour window
- Marketing campaigns
- Transactional notifications at scale
Templates must be submitted to Meta for approval before use.
Template Components
| Component | Description |
|---|
| Header | Optional text, image, video, or document |
| Body | Main message content with variables |
| Footer | Optional footer text |
| Buttons | Optional quick reply or call-to-action buttons |
Variables
Templates support dynamic variables for personalization:
Hello {{1}}, your order #{{2}} has been shipped!
await zavu.messages.send({
to: "+1234567890",
templateId: "order_shipped",
variables: ["John", "12345"]
});
Summary
| Concept | Description |
|---|
| Channels | SMS, WhatsApp, Telegram - different ways to reach users |
| Messages | Outbound (you → user) or Inbound (user → you) |
| Smart Routing | ML-powered automatic channel selection |
| Fallback | Automatic retry on different channel |
| 24-Hour Window | WhatsApp’s free-form text time limit |
| Senders | Multi-channel message configurations |
| Contacts | User records with per-channel metrics |
| Templates | Pre-approved message formats |