Quickstart

Send your first message in under 5 minutes

Follow these steps to start sending messages with Zavu.

1. Create an Account

Sign up at dashboard.zavu.dev. You’ll be prompted to create your first team and project.

Projects isolate your messaging by environment (development, staging, production) or by application.

2. Create a Sender

A Sender is your messaging identity — it defines who sends messages and which channels are available. Go to Senders in the sidebar and create your first sender.

1. Click Add Sender
2. Give it a name (e.g., “Notifications”, “Support”)
3. Assign a phone number (see step 3) or configure channels directly
4. Set as default sender

Your default sender is used automatically when you send a message without specifying one. You can override it with the Zavu-Sender header.

3. Configure Channels

Each sender can have multiple channels. The channels you need depend on your use case:

Channel	Requirements	What It’s For
SMS	Phone number with SMS capability	Universal reach, alerts, OTP
WhatsApp	Phone number + WABA connection	Rich messaging, cost-effective
Email	Verified domain (DKIM records)	Transactional emails, newsletters
Telegram	Bot token from @BotFather	Bot messaging, tech audiences
Instagram	Meta App + Business Account	Social messaging
Voice	Phone number with voice capability	Text-to-speech calls, verification

Channels that need a phone number

SMS, WhatsApp, and Voice require a phone number. You can purchase one directly in Zavu:

1. Go to Phone Numbers

   Navigate to Phone Numbers in the sidebar.

2. Search and purchase

   Search by country or area code and purchase a number.

3. Assign to your sender

   Assign the phone number to your sender. SMS and Voice are automatically enabled based on the number’s capabilities.

For WhatsApp, you also need to connect a WhatsApp Business Account (WABA) through Meta’s embedded signup in the dashboard.

Channels without a phone number

Email, Telegram, and Instagram each have their own setup:

• Email: Add and verify your domain with DKIM records in Email Domains
• Telegram: Create a bot via @BotFather and paste the token in your sender’s Channels tab
• Instagram: Connect your Meta App and Instagram Business Account via the dashboard

SMS and WhatsApp participate in smart routing and automatic fallback. Other channels must be explicitly specified when sending. See Adding Channels for detailed setup instructions.

4. Create an API Key

Go to Settings → API Keys and generate your first key. See Authentication for details on key types and security.

1. Click Create API Key
2. Give it a descriptive name
3. Copy and store the key securely

Your API key will only be shown once. Store it in your environment variables:

export ZAVUDEV_API_KEY="zv_live_your_api_key_here"

5. Send Your First Message

Install the SDK for your language:

TypeScript

npm add @zavudev/sdk
# or: bun add @zavudev/sdk

Server-side only — The Zavu SDKs are designed for server-side environments (Node.js, Python, Ruby, Go, PHP, serverless functions). Never use them in browser/frontend code as this exposes your API key. See Frontend Integration for the proxy pattern.

Then send your first message:

TypeScript

import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev({
  apiKey: process.env['ZAVUDEV_API_KEY'], // This is the default and can be omitted
});

const result = await zavu.messages.send({
  to: "[phone]",
  text: "Hello from Zavu!",
});

console.log("Message ID:", result.message.id);
console.log("Status:", result.message.status);

Success! You should receive a 202 Accepted response. Your default sender handles routing automatically — if both SMS and WhatsApp are configured, Zavu selects the optimal channel based on cost and deliverability.

Sending on a specific channel

To target a specific channel, pass the channel parameter:

TypeScript

// Send via WhatsApp
await zavu.messages.send({
  to: "[phone]",
  text: "Hello via WhatsApp!",
  channel: "whatsapp",
});

// Send via Email
await zavu.messages.send({
  to: "[e-mail]",
  channel: "email",
  subject: "Hello from Zavu",
  text: "Your first email message!",
});

// Send via Voice (text-to-speech)
await zavu.messages.send({
  to: "[phone]",
  channel: "voice",
  text: "Your verification code is 1 2 3 4 5 6",
});

Response

{
  "message": {
    "id": "jd70x0ms07pbfyknb2hj8akznn7whac3",
    "to": "[phone]",
    "from": "[phone]",
    "channel": "sms",
    "status": "queued",
    "messageType": "text",
    "text": "Hello from Zavu!",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

6. Configure Webhooks (Optional)

To receive delivery status updates and incoming messages, configure a webhook on your sender.

1. Go to Senders and select your sender
2. Add a Webhook URL (must be HTTPS)
3. Select the events you want to receive

Webhook events include:

• message.queued - Message accepted
• message.sent - Message sent to carrier
• message.delivered - Message delivered to recipient
• message.failed - Message failed to deliver
• message.inbound - Incoming message received
• conversation.new - New conversation started

Sandbox Mode

New projects start in Sandbox Mode which only allows sending to verified phone numbers. This prevents accidental sends during development.

To verify a number for sandbox testing:

1. Go to Sandbox in the sidebar
2. Add your test phone numbers
3. Verify via SMS code

Contact support to enable production mode when you’re ready to send to any number.

Next Steps

Sending Messages

Learn different ways to send messages

Adding Channels

Configure SMS, WhatsApp, Email, Telegram, and more

WhatsApp

Send rich WhatsApp messages with media and templates

API Reference

Explore all endpoints