# Broadcasts

> Send messages to thousands of recipients with a single API call

Broadcasts let you send the same message to many recipients without making individual API calls. Perfect for marketing campaigns, announcements, and bulk notifications.

## Why Use Broadcasts?

Instead of making 10,000 individual API calls:

```typescript
// Without broadcasts - 10,000 API calls
for (const contact of contacts) {
  await zavu.messages.send({
    to: contact.phone,
    text: "Black Friday sale starts now!",
  });
}
```

Use a single broadcast:

```typescript
// With broadcasts - 3 API calls total
const broadcast = await zavu.broadcasts.create({
  name: "Black Friday Campaign",
  channel: "sms",
  text: "Black Friday sale starts now!",
});

await zavu.broadcasts.contacts.add(broadcast.id, {
  contacts: contacts.map(c => ({ recipient: c.phone })),
});

await zavu.broadcasts.send(broadcast.id);
```

## Key Features

  - **Batch Processing**: Add up to 1,000 contacts per request. Zavu handles rate limiting and delivery optimization automatically.
  - **Personalization**: Customize each message with per-contact template variables like names, order IDs, or custom fields.
  - **Scheduling**: Schedule broadcasts for future delivery. Perfect for time-zone aware campaigns.
  - **Real-time Progress**: Poll for delivery progress with instant updates on sent, delivered, and failed counts.

## Balance Reservation

When you send a broadcast, Zavu reserves the estimated cost from your balance. This ensures funds are available for the entire campaign and prevents overspending.

```
Balance: $100.00 → Send Broadcast ($25 estimated) → Available: $75.00, Reserved: $25.00
```

Reserved funds are released when the broadcast completes or is cancelled. [Learn more](https://www.zavu.dev/docs/guides/broadcasts/sending#balance-reservation)

## Broadcast Lifecycle

```
Draft → Pending Review → Approved → Scheduled (optional) → Sending → Completed
              ↓                                               ↓
          Rejected ────→ Escalated ────→ Rejected Final   Cancelled
              ↑              ↓
              └──── Edit ←───┘
```

| Status | Description |
|--------|-------------|
| `draft` | Initial state. Add/remove contacts freely. |
| `pending_review` | Content being reviewed by AI. |
| `pending_admin_review` | Passed automated review, waiting for a person at Zavu. Every channel except email (and WhatsApp on an approved template, which skips review) stops here. |
| `approved` | Review passed, ready to send. |
| `rejected` | Content rejected, edit and retry. |
| `escalated` | Sent to human review. |
| `rejected_final` | Rejected by human review (cannot appeal). |
| `scheduled` | Waiting to send at scheduled time. |
| `sending` | Messages being delivered. |
| `completed` | All messages processed. |
| `cancelled` | Broadcast stopped before completion. Can be cancelled from any status up to and including `sending`, except `paused` and `rejected_final`. |

## Quick Example

```typescript
import Zavudev from '@zavudev/sdk';

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

// 1. Create the broadcast
const broadcast = await zavu.broadcasts.create({
  name: "Order Confirmation Campaign",
  channel: "sms",
  text: "Hi {{name}}, your order #{{order_id}} has shipped!",
});

// 2. Add contacts with personalization
await zavu.broadcasts.contacts.add(broadcast.id, {
  contacts: [
    {
      recipient: "+14155551234",
      templateVariables: { name: "John", order_id: "ORD-001" }
    },
    {
      recipient: "+14155555678",
      templateVariables: { name: "Jane", order_id: "ORD-002" }
    },
  ],
});

// 3. Send immediately
await zavu.broadcasts.send(broadcast.id);

// 4. Check progress
const progress = await zavu.broadcasts.progress(broadcast.id);
console.log(`${progress.percentComplete}% complete`);
```

```bash
# 1. Create the broadcast
curl -X POST https://api.zavu.dev/v1/broadcasts \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Confirmation Campaign",
    "channel": "sms",
    "text": "Hi {{name}}, your order #{{order_id}} has shipped!"
  }'

# 2. Add contacts
curl -X POST https://api.zavu.dev/v1/broadcasts/{broadcastId}/contacts \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {"recipient": "+14155551234", "templateVariables": {"name": "John", "order_id": "ORD-001"}},
      {"recipient": "+14155555678", "templateVariables": {"name": "Jane", "order_id": "ORD-002"}}
    ]
  }'

# 3. Send the broadcast
curl -X POST https://api.zavu.dev/v1/broadcasts/{broadcastId}/send \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

# 4. Check progress
curl https://api.zavu.dev/v1/broadcasts/{broadcastId}/progress \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"
```

## Supported Channels

| Channel | Message Types | Personalization |
|---------|--------------|-----------------|
| SMS | Text | Template variables |
| WhatsApp | Text, Image, Video, Audio, Document, Template | Template variables |
| Email | Text, HTML | Template variables |

> **Info:**
> WhatsApp broadcasts using free-form messages (non-template) require an open 24-hour conversation window with each recipient. Use WhatsApp templates for marketing campaigns to recipients who haven't messaged you recently.

## Limits

| Limit | Default | Notes |
|-------|---------|-------|
| Contacts per request | 1,000 | Add contacts in batches |
| Contacts per broadcast | 1,000 | Contact support to increase |
| Concurrent broadcasts | No limit | Rate limits still apply |

## Next Steps

  - [Creating Broadcasts](https://www.zavu.dev/docs/guides/broadcasts/creating-broadcasts): Configure message content and channel settings
  - [Adding Contacts](https://www.zavu.dev/docs/guides/broadcasts/adding-contacts): Batch upload and personalization
  - [Sending & Scheduling](https://www.zavu.dev/docs/guides/broadcasts/sending): Send immediately or schedule for later
  - [Tracking Progress](https://www.zavu.dev/docs/guides/broadcasts/tracking-progress): Monitor delivery in real-time

## API Reference

Manage broadcasts programmatically:

- [List broadcasts](https://www.zavu.dev/docs/api-reference/list-broadcasts) — fetch all broadcast campaigns
- [Get a broadcast](https://www.zavu.dev/docs/api-reference/get-broadcast) — retrieve broadcast details and status
- [Get broadcast progress](https://www.zavu.dev/docs/api-reference/get-broadcast-progress) — real-time delivery metrics