Skip to main content
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

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

ParameterTypeRequiredDescription
namestringYesName for identifying this broadcast
channelstringYessms, whatsapp, or email
messageTypestringNoMessage type (default: text)
textstringConditionalMessage body (required for text messages)
contentobjectConditionalMedia/template content for rich messages
subjectstringConditionalEmail subject (required for email channel)
htmlBodystringNoHTML body for email messages
scheduledAtstringNoISO 8601 datetime for scheduled delivery
metadataobjectNoCustom key-value pairs
idempotencyKeystringNoUnique 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: `
    <h1>Hello {{name}}!</h1>
    <p>Here are this month's highlights...</p>
  `,
});

​
Using Template Variables

Template variables use {{variable_name}} syntax. Variables can be set at two levels:
  1. Broadcast level: Default values for all contacts
  2. 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.addContacts(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: 
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