# Messaging Quickstart — Send Your First Message

> Send your first SMS, WhatsApp or Email message with Zavu in under 5 minutes. Step-by-step guide with code samples in TypeScript and cURL.

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

> **Info:**
> Want Zavu to run the conversation instead of you? The
> [agent quickstart](https://www.zavu.dev/docs/quickstart) deploys an AI agent that answers these same
> channels, including phone calls.

> **Note:**
> This quickstart uses API v1 and its senders. Prefer to send from an address,
> with one webhook for the project? See [API v2](https://www.zavu.dev/docs/api-v2/overview). v1 stays
> supported.

## 1. Create an Account

Sign up at [dashboard.zavu.dev](https://dashboard.zavu.dev). You'll be prompted to create your first team and project.

> **Info:**
> Projects isolate your messaging by environment (development, staging, production) or by application.

## 2. Create a Sender

A [**Sender**](https://www.zavu.dev/docs/concepts/senders) 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

> **Tip:**
> Your [**default sender**](https://www.zavu.dev/docs/concepts/senders#default-sender) is used automatically when you send a message without specifying one. You can override it with the [`Zavu-Sender` header](https://www.zavu.dev/docs/authentication#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](https://www.zavu.dev/docs/guides/sending-messages/sms)** | [Phone number](https://www.zavu.dev/docs/concepts/phone-numbers) with SMS capability | Universal reach, alerts, OTP |
| **[WhatsApp](https://www.zavu.dev/docs/guides/whatsapp/overview)** | Phone number + [WABA connection](https://www.zavu.dev/docs/guides/whatsapp/connect-whatsapp) | Rich messaging, cost-effective |
| **[Email](https://www.zavu.dev/docs/guides/sending-messages/email)** | [Verified domain](https://www.zavu.dev/docs/guides/email/setup) (DKIM records) | Transactional emails, newsletters |
| **[Telegram](https://www.zavu.dev/docs/guides/telegram/overview)** | 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](https://www.zavu.dev/docs/concepts/phone-numbers). You can [purchase one](https://www.zavu.dev/docs/guides/phone-numbers/purchasing) directly in Zavu:

  
#### Go to Phone Numbers

    Navigate to **Phone Numbers** in the sidebar.
  
  
#### Search and purchase

    Search by country or area code and purchase a number.
  
  
#### 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](https://www.zavu.dev/docs/guides/whatsapp/connect-whatsapp) (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](https://www.zavu.dev/docs/guides/email/setup) with DKIM records in **Email Domains**
- **Telegram**: [Create a bot](https://www.zavu.dev/docs/guides/telegram/setup) via [@BotFather](https://t.me/BotFather) and paste the token in your sender's Channels tab
- **Instagram**: Connect your Meta App and Instagram Business Account via the dashboard

> **Info:**
> SMS and WhatsApp participate in [**smart routing**](https://www.zavu.dev/docs/concepts/senders#smart-routing) and [**automatic fallback**](https://www.zavu.dev/docs/concepts/senders#automatic-fallback). Other channels must be explicitly specified when sending. See [Adding Channels](https://www.zavu.dev/docs/guides/senders/adding-channels) for detailed setup instructions.

## 4. Create an API Key

Go to **Settings** → **API Keys** and generate your first key. See [Authentication](https://www.zavu.dev/docs/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

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

```bash
export ZAVUDEV_API_KEY="zv_live_your_api_key_here"
```

## 5. Send Your First Message

Install the TypeScript SDK. From any other language, use the cURL example below or see [SDKs](https://www.zavu.dev/docs/sdks/overview) for your options:

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

> **Warning:**
> **Server-side only** — Call Zavu from your server or a serverless function. Never call it from browser/frontend code as this exposes your API key. See [Frontend Integration](https://www.zavu.dev/docs/authentication#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: "+14155551234",
  text: "Hello from Zavu!",
});

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

```bash
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "text": "Hello from Zavu!"
  }'
```

> **Check:**
> **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: "+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

```json
{
  "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](https://www.zavu.dev/docs/guides/receiving-messages/webhooks) 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](https://www.zavu.dev/docs/guides/receiving-messages/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](https://www.zavu.dev/docs/concepts/sending-limits) for the numbers and the error codes.

## Next Steps

  - [Sending Messages](https://www.zavu.dev/docs/guides/sending-messages/easy-way): Learn different ways to send messages
  - [Adding Channels](https://www.zavu.dev/docs/guides/senders/adding-channels): Configure SMS, WhatsApp, Email, Telegram, and more
  - [WhatsApp](https://www.zavu.dev/docs/guides/whatsapp/overview): Send rich WhatsApp messages with media and templates
  - [API Reference](https://www.zavu.dev/docs/api-reference): Explore all endpoints