Creating Broadcasts

Create a broadcast to define your message content and delivery channel. Broadcasts start in draft status, allowing you to add contacts before sending.

Basic Broadcast

const broadcast = await zavu.broadcasts.create({
  name: "Weekly Newsletter",
  channel: "sms",
  text: "This week's top deals are live! Shop now at example.com/deals",
});

broadcast = zavu.broadcasts.create(
    name="Weekly Newsletter",
    channel="sms",
    text="This week's top deals are live! Shop now at example.com/deals"
)

broadcast = client.broadcasts.create(
  name: "Weekly Newsletter",
  channel: "sms",
  text: "This week's top deals are live! Shop now at example.com/deals"
)

broadcast, _ := client.Broadcasts.New(context.TODO(), zavudev.BroadcastCreateParams{
	Name:    zavudev.String("Weekly Newsletter"),
	Channel: zavudev.String("sms"),
	Text:    zavudev.String("This week's top deals are live! Shop now at example.com/deals"),
})

$broadcast = $client->broadcasts->create([
    'name' => 'Weekly Newsletter',
    'channel' => 'sms',
    'text' => "This week's top deals are live! Shop now at example.com/deals",
]);

curl -X POST https://api.zavu.dev/v1/broadcasts \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Newsletter",
    "channel": "sms",
    "text": "This week'"'"'s top deals are live! Shop now at example.com/deals"
  }'

Response

{
  "id": "brd_abc123",
  "name": "Weekly Newsletter",
  "status": "draft",
  "channel": "sms",
  "messageType": "text",
  "text": "This week's top deals are live! Shop now at example.com/deals",
  "totalContacts": 0,
  "pendingCount": 0,
  "sendingCount": 0,
  "deliveredCount": 0,
  "failedCount": 0,
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Name for identifying this broadcast
`channel`	string	Yes	`sms`, `whatsapp`, or `email`
`messageType`	string	No	Message type (default: `text`)
`text`	string	Conditional	Message body (required for text messages)
`content`	object	Conditional	Media/template content for rich messages
`subject`	string	Conditional	Email subject (required for email channel)
`htmlBody`	string	No	HTML body for email messages
`scheduledAt`	string	No	ISO 8601 datetime for scheduled delivery
`metadata`	object	No	Custom key-value pairs
`idempotencyKey`	string	No	Unique key to prevent duplicates

Channel-Specific Examples

SMS Broadcast

const broadcast = await zavu.broadcasts.create({
  name: "Flash Sale Alert",
  channel: "sms",
  text: "FLASH SALE: 50% off everything for the next 2 hours! Use code FLASH50. Reply STOP to opt out.",
});

WhatsApp Text Broadcast

const broadcast = await zavu.broadcasts.create({
  name: "Order Update",
  channel: "whatsapp",
  text: "Hi {{name}}! Your order #{{order_id}} is out for delivery. Track it here: {{tracking_url}}",
});

WhatsApp Template Broadcast

For marketing messages to recipients outside the 24-hour window, use approved templates:

const broadcast = await zavu.broadcasts.create({
  name: "Holiday Promo",
  channel: "whatsapp",
  messageType: "template",
  content: {
    templateId: "tmpl_holiday_sale",
    templateVariables: {
      "1": "Holiday",  // Broadcast-level defaults
      "2": "20%",
    },
  },
});

Per-contact template variables can override broadcast-level defaults when adding contacts.

WhatsApp Media Broadcast

const broadcast = await zavu.broadcasts.create({
  name: "Product Launch",
  channel: "whatsapp",
  messageType: "image",
  text: "Introducing our newest product! Available now.",
  content: {
    mediaUrl: "https://example.com/product-image.jpg",
  },
});

Email Broadcast

const broadcast = await zavu.broadcasts.create({
  name: "Monthly Newsletter",
  channel: "email",
  subject: "Your {{month}} Newsletter from {{company}}",
  text: "Hi {{name}}, here are this month's highlights...",
  htmlBody: `
    <h2>Hello {{name}}!</h2>
    <p>Here are this month's highlights...</p>
  `,
});

Using Template Variables

Template variables use {{variable_name}} syntax. Variables can be set at two levels:

Broadcast level: Default values for all contacts
Contact level: Override defaults for specific contacts

// Broadcast with default variables
const broadcast = await zavu.broadcasts.create({
  name: "Welcome Campaign",
  channel: "sms",
  text: "Welcome to {{company}}, {{name}}! Use code {{promo_code}} for 10% off.",
});

// Contact-level overrides when adding contacts
await zavu.broadcasts.contacts.add(broadcast.id, {
  contacts: [
    {
      recipient: "+14155551234",
      templateVariables: {
        name: "John",
        company: "Acme Inc",
        promo_code: "JOHN10",
      },
    },
    {
      recipient: "+14155555678",
      templateVariables: {
        name: "Jane",
        company: "Acme Inc",
        promo_code: "JANE10",
      },
    },
  ],
});

Using a Specific Sender

By default, broadcasts use your project’s default sender. Specify a different sender:

const broadcast = await zavu.broadcasts.create({
  name: "Support Alert",
  channel: "sms",
  text: "System maintenance scheduled for tonight.",
  senderId: "snd_support123",
});

broadcast = zavu.broadcasts.create(
    name="Support Alert",
    channel="sms",
    text="System maintenance scheduled for tonight.",
    sender_id="snd_support123"
)

broadcast = client.broadcasts.create(
  name: "Support Alert",
  channel: "sms",
  text: "System maintenance scheduled for tonight.",
  sender_id: "snd_support123"
)

broadcast, _ := client.Broadcasts.New(context.TODO(), zavudev.BroadcastCreateParams{
	Name:     zavudev.String("Support Alert"),
	Channel:  zavudev.String("sms"),
	Text:     zavudev.String("System maintenance scheduled for tonight."),
	SenderID: zavudev.String("snd_support123"),
})

$broadcast = $client->broadcasts->create([
    'name' => 'Support Alert',
    'channel' => 'sms',
    'text' => 'System maintenance scheduled for tonight.',
    'senderId' => 'snd_support123',
]);

curl -X POST https://api.zavu.dev/v1/broadcasts \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Alert",
    "channel": "sms",
    "text": "System maintenance scheduled for tonight.",
    "senderId": "snd_support123"
  }'

Updating a Broadcast

Update a broadcast while it’s still in draft status:

await zavu.broadcasts.update(broadcast.id, {
  name: "Updated Campaign Name",
  text: "Updated message content",
});

Broadcasts can only be updated while in draft status. Once sending begins, the message content is locked.

Deleting a Broadcast

Delete a draft broadcast:

await zavu.broadcasts.delete(broadcast.id);

Only draft broadcasts can be deleted. Use the cancel endpoint for broadcasts that have started sending.

Idempotency

Prevent duplicate broadcasts with an idempotency key:

const broadcast = await zavu.broadcasts.create({
  name: "Daily Reminder",
  channel: "sms",
  text: "Don't forget your daily check-in!",
  idempotencyKey: "daily-reminder-2024-01-15",
});

If you make another request with the same idempotencyKey, the API returns the existing broadcast instead of creating a duplicate.

Next Steps

Adding Contacts

Learn how to add recipients to your broadcast

Getting Started

Build agents

Send & receive

Operate

Developer tools

Integrations

Creating Broadcasts

Basic Broadcast

Response

Parameters

Channel-Specific Examples

SMS Broadcast

WhatsApp Text Broadcast

WhatsApp Template Broadcast

WhatsApp Media Broadcast

Email Broadcast

Using Template Variables

Using a Specific Sender

Updating a Broadcast

Deleting a Broadcast

Idempotency

Next Steps

Adding Contacts

​Basic Broadcast

​Response

​Parameters

​Channel-Specific Examples

​SMS Broadcast

​WhatsApp Text Broadcast

​WhatsApp Template Broadcast

​WhatsApp Media Broadcast

​Email Broadcast

​Using Template Variables

​Using a Specific Sender

​Updating a Broadcast

​Deleting a Broadcast

​Idempotency

​Next Steps

Adding Contacts

Basic Broadcast

Response

Parameters

Channel-Specific Examples

SMS Broadcast

WhatsApp Text Broadcast

WhatsApp Template Broadcast

WhatsApp Media Broadcast

Email Broadcast

Using Template Variables

Using a Specific Sender

Updating a Broadcast

Deleting a Broadcast

Idempotency

Next Steps