Broadcasts

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:

// 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:

// 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.addContacts(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

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.
`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.

Quick Example

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.addContacts(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.getProgress(broadcast.id);
console.log(`${progress.percentComplete}% complete`);

import os
from zavudev import Zavudev

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

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

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

# 3. Send immediately
zavu.broadcasts.send(broadcast.id)

# 4. Check progress
progress = zavu.broadcasts.get_progress(broadcast.id)
print(f"{progress.percent_complete}% complete")

require "zavudev"

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

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

# 2. Add contacts with personalization
client.broadcasts.add_contacts(broadcast.id, contacts: [
  {
    recipient: "+14155551234",
    template_variables: { name: "John", order_id: "ORD-001" }
  },
  {
    recipient: "+14155555678",
    template_variables: { name: "Jane", order_id: "ORD-002" }
  },
])

# 3. Send immediately
client.broadcasts.send(broadcast.id)

# 4. Check progress
progress = client.broadcasts.get_progress(broadcast.id)
puts "#{progress.percent_complete}% complete"

package main

import (
	"context"
	"fmt"
	"os"

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

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

	// 1. Create the broadcast
	broadcast, _ := client.Broadcasts.Create(context.TODO(), zavudev.BroadcastCreateParams{
		Name:    zavudev.String("Order Confirmation Campaign"),
		Channel: zavudev.String("sms"),
		Text:    zavudev.String("Hi {{name}}, your order #{{order_id}} has shipped!"),
	})

	// 2. Add contacts with personalization
	client.Broadcasts.AddContacts(context.TODO(), broadcast.ID, zavudev.BroadcastAddContactsParams{
		Contacts: []zavudev.BroadcastContactInput{
			{
				Recipient:         zavudev.String("+14155551234"),
				TemplateVariables: map[string]string{"name": "John", "order_id": "ORD-001"},
			},
			{
				Recipient:         zavudev.String("+14155555678"),
				TemplateVariables: map[string]string{"name": "Jane", "order_id": "ORD-002"},
			},
		},
	})

	// 3. Send immediately
	client.Broadcasts.Send(context.TODO(), broadcast.ID, zavudev.BroadcastSendParams{})

	// 4. Check progress
	progress, _ := client.Broadcasts.GetProgress(context.TODO(), broadcast.ID)
	fmt.Printf("%v%% complete\n", progress.PercentComplete)
}

$client = new Zavudev\Client(apiKey: getenv('ZAVUDEV_API_KEY'));

// 1. Create the broadcast
$broadcast = $client->broadcasts->create([
    'name' => 'Order Confirmation Campaign',
    'channel' => 'sms',
    'text' => 'Hi {{name}}, your order #{{order_id}} has shipped!',
]);

// 2. Add contacts with personalization
$client->broadcasts->addContacts($broadcast->id, [
    'contacts' => [
        [
            'recipient' => '+14155551234',
            'templateVariables' => ['name' => 'John', 'order_id' => 'ORD-001'],
        ],
        [
            'recipient' => '+14155555678',
            'templateVariables' => ['name' => 'Jane', 'order_id' => 'ORD-002'],
        ],
    ],
]);

// 3. Send immediately
$client->broadcasts->send($broadcast->id);

// 4. Check progress
$progress = $client->broadcasts->getProgress($broadcast->id);
echo "{$progress->percentComplete}% complete\n";

# 1. Create the broadcast
curl -X POST https://api.zavu.dev/v1/broadcasts \
  -H "Authorization: Bearer $ZAVU_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 $ZAVU_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 $ZAVU_API_KEY"

# 4. Check progress
curl https://api.zavu.dev/v1/broadcasts/{broadcastId}/progress \
  -H "Authorization: Bearer $ZAVU_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

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

Configure message content and channel settings

Adding Contacts

Batch upload and personalization

Sending & Scheduling

Send immediately or schedule for later

Tracking Progress

Monitor delivery in real-time

API Reference

Manage broadcasts programmatically:

List broadcasts — fetch all broadcast campaigns
Get a broadcast — retrieve broadcast details and status
Get broadcast progress — real-time delivery metrics

Getting Started

Concepts

Guides

Why Use Broadcasts?

Key Features

Batch Processing

Personalization

Scheduling

Real-time Progress

Balance Reservation

Broadcast Lifecycle

Quick Example

Supported Channels

Limits

Next Steps

Creating Broadcasts

Adding Contacts

Sending & Scheduling

Tracking Progress

API Reference

​Why Use Broadcasts?

​Key Features

Batch Processing

Personalization

Scheduling

Real-time Progress

​Balance Reservation

​Broadcast Lifecycle

​Quick Example

​Supported Channels

​Limits

​Next Steps

Creating Broadcasts

Adding Contacts

Sending & Scheduling

Tracking Progress

​API Reference

Why Use Broadcasts?

Key Features

Balance Reservation

Broadcast Lifecycle

Quick Example

Supported Channels

Limits

Next Steps

API Reference