Broadcasts

Broadcasts allow you to send messages to multiple recipients in a single campaign.

Create Broadcast

TypeScript
const result = await client.broadcasts.create({
  name: "Black Friday Sale",
  channel: "sms",
  text: "Hi {{name}}, check out our Black Friday deals! Use code FRIDAY20 for 20% off.",
});

console.log(result.broadcast.id); // brd_xxx
console.log(result.broadcast.status); // draft

WhatsApp Template Broadcast

TypeScript
const result = await client.broadcasts.create({
  name: "Order Confirmation Campaign",
  channel: "whatsapp",
  messageType: "template",
  content: {
    templateId: "tpl_abc123",
  },
});

Email Broadcast

TypeScript
const result = await client.broadcasts.create({
  name: "Newsletter",
  channel: "email",
  emailSubject: "Your Weekly Update",
  text: "Hi {{name}}, here's what's new this week...",
});

Get Broadcast

TypeScript
const result = await client.broadcasts.retrieve({
  broadcastId: "brd_abc123",
});

console.log(result.broadcast.name);
console.log(result.broadcast.status);
console.log(result.broadcast.totalContacts);

List Broadcasts

TypeScript
const result = await client.broadcasts.list({});

for (const broadcast of result.items) {
  console.log(broadcast.id, broadcast.name, broadcast.status);
}

// Filter by status
const result = await client.broadcasts.list({
  status: "completed",
  limit: 50,
});

Update Broadcast

Update a broadcast in draft status:

TypeScript
const result = await client.broadcasts.update({
  broadcastId: "brd_abc123",
  name: "Updated Campaign Name",
  text: "New message content with {{name}}",
});

Add Contacts

Add contacts to a broadcast (max 1000 per request):

TypeScript
const result = await client.broadcasts.contacts.add({
  broadcastId: "brd_abc123",
  contacts: [
    {
      recipient: "+14155551234",
      templateVariables: {
        name: "John",
        order_id: "ORD-001",
      },
    },
    {
      recipient: "+14155555678",
      templateVariables: {
        name: "Jane",
        order_id: "ORD-002",
      },
    },
  ],
});

console.log(result.added); // 2
console.log(result.duplicates); // 0
console.log(result.invalid); // 0

List Broadcast Contacts

TypeScript
const result = await client.broadcasts.contacts.list({
  broadcastId: "brd_abc123",
  status: "pending",
  limit: 100,
});

for (const contact of result.items) {
  console.log(contact.recipient, contact.status);
}

Remove Contact

TypeScript
await client.broadcasts.contacts.remove({
  broadcastId: "brd_abc123",
  contactId: "bcon_xyz789",
});

Send Broadcast

Start sending immediately:

TypeScript
const result = await client.broadcasts.send({
  broadcastId: "brd_abc123",
});

console.log(result.broadcast.status); // sending

Schedule for later:

TypeScript
const result = await client.broadcasts.send({
  broadcastId: "brd_abc123",
  scheduledAt: "2024-01-15T10:00:00Z",
});

console.log(result.broadcast.status); // scheduled

Reschedule Broadcast

Change the scheduled time for a broadcast in scheduled status:

TypeScript
const result = await client.broadcasts.reschedule({
  broadcastId: "brd_abc123",
  scheduledAt: "2024-01-16T14:00:00Z",
});

console.log(result.broadcast.scheduledAt); // 2024-01-16T14:00:00.000Z

Get Progress

Monitor broadcast progress in real-time:

TypeScript
const result = await client.broadcasts.progress({
  broadcastId: "brd_abc123",
});

console.log(result.status); // sending
console.log(result.total); // 5000
console.log(result.delivered); // 2350
console.log(result.failed); // 50
console.log(result.percentComplete); // 48.0
console.log(result.estimatedCompletionAt);

Cancel Broadcast

TypeScript
const result = await client.broadcasts.cancel({
  broadcastId: "brd_abc123",
});

console.log(result.broadcast.status); // cancelled

Delete Broadcast

Delete a broadcast in draft status:

TypeScript
await client.broadcasts.delete({
  broadcastId: "brd_abc123",
});