Messaging Quickstart — Send Your First Message

Follow these steps to send messages from your own backend, with Zavu as the transport.

1. Create an Account

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

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

3. Configure Channels

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

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

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

5. Send Your First Message

Install the TypeScript SDK. From any other language, use the cURL example below or see SDKs for your options:

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

Then send your first message:

TypeScriptcURLCopy
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: "+14155551234",
  text: "Hello from Zavu!",
});

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

Sending on a specific channel

To target a specific channel, pass the channel parameter:

TypeScriptCopy
// Send via WhatsApp
await zavu.messages.send({
  to: "+14155551234",
  text: "Hello via WhatsApp!",
  channel: "whatsapp",
});

// Send via Email
await zavu.messages.send({
  to: "user@example.com",
  channel: "email",
  subject: "Hello from Zavu",
  text: "Your first email message!",
});

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

Response

JSONCopy
{
  "message": {
    "id": "jd70x0ms07pbfyknb2hj8akznn7whac3",
    "to": "+14155551234",
    "from": "+14155559876",
    "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

Sending limits for new accounts

A new account sends on every channel, to any destination, right away. There is nothing to verify first.

What a new account has is a lower daily ceiling: 25 SMS, 5 calls and 100 conversational messages a day. Verifying your identity, adding a payment method, settling a deposit or subscribing raises it. Each is self-serve in the dashboard; no support ticket is needed.

Two more things apply to US and Canadian SMS, and to every message:

• SMS to a +1 number needs an approved 10DLC campaign, which carriers require. Without one, 403 ten_dlc_required.
• Messages on sms, sms_oneway, email and voice are read before they are sent. One can be held briefly for review — it stays queued — or refused, in which case it fails with RISK_BLOCKED, RISK_REJECTED or RISK_REVIEW_EXPIRED in errorCode.

See Sending limits for the numbers and the error codes.

Next Steps