> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](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.
</Info>

## 2. Create a Sender

A [**Sender**](/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**](/concepts/senders#default-sender) is used automatically when you send a message without specifying one. You can override it with the [`Zavu-Sender` header](/authentication#zavu-sender-header).
</Tip>

## 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](/guides/sending-messages/sms)**     | [Phone number](/concepts/phone-numbers) with SMS capability         | Universal reach, alerts, OTP       |
| **[WhatsApp](/guides/whatsapp/overview)**   | Phone number + [WABA connection](/guides/whatsapp/connect-whatsapp) | Rich messaging, cost-effective     |
| **[Email](/guides/sending-messages/email)** | [Verified domain](/guides/email/setup) (DKIM records)               | Transactional emails, newsletters  |
| **[Telegram](/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](/concepts/phone-numbers). You can [purchase one](/guides/phone-numbers/purchasing) directly in Zavu:

<Steps>
  <Step title="Go to Phone Numbers">
    Navigate to **Phone Numbers** in the sidebar.
  </Step>

  <Step title="Search and purchase">
    Search by country or area code and purchase a number.
  </Step>

  <Step title="Assign to your sender">
    Assign the phone number to your sender. SMS and Voice are automatically enabled based on the number's capabilities.
  </Step>
</Steps>

For **WhatsApp**, you also need to [connect a WhatsApp Business Account](/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](/guides/email/setup) with DKIM records in **Email Domains**
* **Telegram**: [Create a bot](/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**](/concepts/senders#smart-routing) and [**automatic fallback**](/concepts/senders#automatic-fallback). Other channels must be explicitly specified when sending. See [Adding Channels](/guides/senders/adding-channels) for detailed setup instructions.
</Info>

## 4. Create an API Key

Go to **Settings** → **API Keys** and generate your first key. See [Authentication](/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 theme={null}
  export ZAVUDEV_API_KEY="zv_live_your_api_key_here"
  ```
</Warning>

## 5. Send Your First Message

Install the SDK for your language:

<CodeGroup>
  ```bash TypeScript theme={null}
  npm add @zavudev/sdk
  # or: bun add @zavudev/sdk
  ```

  ```bash Python theme={null}
  pip install zavudev
  # or: uv add zavudev
  ```

  ```bash Ruby theme={null}
  gem install zavudev
  ```

  ```bash Go theme={null}
  go get github.com/zavudev/sdk-go
  ```

  ```bash PHP theme={null}
  composer require zavudev/sdk
  ```
</CodeGroup>

<Warning>
  **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](/authentication#frontend-integration) for the proxy pattern.
</Warning>

Then send your first message:

<CodeGroup>
  ```typescript TypeScript theme={null}
  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);
  ```

  ```python Python theme={null}
  import os
  from zavudev import Zavudev

  zavu = Zavudev(
      api_key=os.environ.get("ZAVUDEV_API_KEY"),  # This is the default and can be omitted
  )

  result = zavu.messages.send(
      to="+14155551234",
      text="Hello from Zavu!",
  )

  print(f"Message ID: {result.message.id}")
  print(f"Status: {result.message.status}")
  ```

  ```ruby Ruby theme={null}
  require "zavudev"

  client = Zavudev::Client.new(api_key: ENV["ZAVUDEV_API_KEY"])

  result = client.messages.send(
    to: "+14155551234",
    text: "Hello from Zavu!"
  )

  puts "Message ID: #{result.message.id}"
  puts "Status: #{result.message.status}"
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"os"

  	"github.com/zavudev/sdk-go"
  	"github.com/zavudev/sdk-go/option"
  )

  func main() {
  	client := zavudev.NewClient(option.WithAPIKey(os.Getenv("ZAVUDEV_API_KEY")))

  	result, _ := client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
  		To:   zavudev.String("+14155551234"),
  		Text: zavudev.String("Hello from Zavu!"),
  	})

  	fmt.Println("Message ID:", result.Message.ID)
  	fmt.Println("Status:", result.Message.Status)
  }
  ```

  ```php PHP theme={null}
  <?php
  $client = new Zavudev\Client(apiKey: getenv('ZAVUDEV_API_KEY'));

  $result = $client->messages->send([
      'to' => '+14155551234',
      'text' => 'Hello from Zavu!',
  ]);

  echo "Message ID: " . $result->message->id . "\n";
  echo "Status: " . $result->message->status . "\n";
  ```

  ```bash cURL theme={null}
  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!"
    }'
  ```
</CodeGroup>

<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.
</Check>

### Sending on a specific channel

To target a specific channel, pass the `channel` parameter:

<CodeGroup>
  ```typescript TypeScript theme={null}
  // 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",
  });
  ```

  ```python Python theme={null}
  # Send via WhatsApp
  zavu.messages.send(
      to="+14155551234",
      text="Hello via WhatsApp!",
      channel="whatsapp",
  )

  # Send via Email
  zavu.messages.send(
      to="user@example.com",
      channel="email",
      subject="Hello from Zavu",
      text="Your first email message!",
  )

  # Send via Voice (text-to-speech)
  zavu.messages.send(
      to="+14155551234",
      channel="voice",
      text="Your verification code is 1 2 3 4 5 6",
  )
  ```

  ```ruby Ruby theme={null}
  # Send via WhatsApp
  client.messages.send(
    to: "+14155551234",
    text: "Hello via WhatsApp!",
    channel: "whatsapp"
  )

  # Send via Email
  client.messages.send(
    to: "user@example.com",
    channel: "email",
    subject: "Hello from Zavu",
    text: "Your first email message!"
  )

  # Send via Voice (text-to-speech)
  client.messages.send(
    to: "+14155551234",
    channel: "voice",
    text: "Your verification code is 1 2 3 4 5 6"
  )
  ```

  ```go Go theme={null}
  // Send via WhatsApp
  client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
  	To:      zavudev.String("+14155551234"),
  	Text:    zavudev.String("Hello via WhatsApp!"),
  	Channel: zavudev.String("whatsapp"),
  })

  // Send via Email
  client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
  	To:      zavudev.String("user@example.com"),
  	Channel: zavudev.String("email"),
  	Subject: zavudev.String("Hello from Zavu"),
  	Text:    zavudev.String("Your first email message!"),
  })

  // Send via Voice (text-to-speech)
  client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
  	To:      zavudev.String("+14155551234"),
  	Channel: zavudev.String("voice"),
  	Text:    zavudev.String("Your verification code is 1 2 3 4 5 6"),
  })
  ```

  ```php PHP theme={null}
  <?php
  // Send via WhatsApp
  $client->messages->send([
      'to' => '+14155551234',
      'text' => 'Hello via WhatsApp!',
      'channel' => 'whatsapp',
  ]);

  // Send via Email
  $client->messages->send([
      'to' => 'user@example.com',
      'channel' => 'email',
      'subject' => 'Hello from Zavu',
      'text' => 'Your first email message!',
  ]);

  // Send via Voice (text-to-speech)
  $client->messages->send([
      'to' => '+14155551234',
      'channel' => 'voice',
      'text' => 'Your verification code is 1 2 3 4 5 6',
  ]);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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](/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](/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

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

<Info>
  Contact support to enable production mode when you're ready to send to any number.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Sending Messages" icon="paper-plane" href="/guides/sending-messages/easy-way">
    Learn different ways to send messages
  </Card>

  <Card title="Adding Channels" icon="layer-group" href="/guides/senders/adding-channels">
    Configure SMS, WhatsApp, Email, Telegram, and more
  </Card>

  <Card title="WhatsApp" icon="whatsapp" href="/guides/whatsapp/overview">
    Send rich WhatsApp messages with media and templates
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Explore all endpoints
  </Card>
</CardGroup>