Broadcasts allow you to send messages to multiple recipients in a single campaign.
Create Broadcast
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
const result = await client.broadcasts.create({
name: "Order Confirmation Campaign",
channel: "whatsapp",
messageType: "template",
content: {
templateId: "tpl_abc123",
},
});
Email Broadcast
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
const result = await client.broadcasts.get({
broadcastId: "brd_abc123",
});
console.log(result.broadcast.name);
console.log(result.broadcast.status);
console.log(result.broadcast.totalContacts);
List Broadcasts
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:
const result = await client.broadcasts.update({
broadcastId: "brd_abc123",
name: "Updated Campaign Name",
text: "New message content with {{name}}",
});
Add contacts to a broadcast (max 1000 per request):
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
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);
}
await client.broadcasts.contacts.remove({
broadcastId: "brd_abc123",
contactId: "bcon_xyz789",
});
Send Broadcast
Start sending immediately:
const result = await client.broadcasts.send({
broadcastId: "brd_abc123",
});
console.log(result.broadcast.status); // sending
Schedule for later:
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:
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
You can only reschedule broadcasts that are in scheduled status. The new time must be in the future.
Get Progress
Monitor broadcast progress in real-time:
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
const result = await client.broadcasts.cancel({
broadcastId: "brd_abc123",
});
console.log(result.broadcast.status); // cancelled
Cancelling a broadcast will skip pending contacts, but messages already queued may still be delivered.
Delete Broadcast
Delete a broadcast in draft status:
await client.broadcasts.delete({
broadcastId: "brd_abc123",
});