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",
});

Response

JSON
{
  "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

TypeScript
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

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

TypeScript
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%",
    },
  },
});

WhatsApp Media Broadcast

TypeScript
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

TypeScript
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

TypeScript
// 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",
});

Updating a Broadcast

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

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

Deleting a Broadcast

Delete a draft broadcast:

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

Idempotency

Prevent duplicate broadcasts with an idempotency key:

TypeScript
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