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

Create Broadcast

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

puts result.broadcast.id     # brd_xxx
puts result.broadcast.status # draft

WhatsApp Template Broadcast

result = client.broadcasts.create(
  name: "Order Confirmation Campaign",
  channel: "whatsapp",
  message_type: "template",
  content: {
    "template_id" => "tpl_abc123"
  }
)

Email Broadcast

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

Get Broadcast

result = client.broadcasts.get(broadcast_id: "brd_abc123")

puts result.broadcast.name
puts result.broadcast.status
puts result.broadcast.total_contacts

List Broadcasts

result = client.broadcasts.list

result.items.each do |broadcast|
  puts "#{broadcast.id} #{broadcast.name} #{broadcast.status}"
end

# Filter by status
result = client.broadcasts.list(
  status: "completed",
  limit: 50
)

Update Broadcast

Update a broadcast in draft status:
result = client.broadcasts.update(
  broadcast_id: "brd_abc123",
  name: "Updated Campaign Name",
  text: "New message content with {{name}}"
)

Add Contacts

Add contacts to a broadcast (max 1000 per request):
result = client.broadcasts.contacts.add(
  broadcast_id: "brd_abc123",
  contacts: [
    {
      "recipient" => "+14155551234",
      "template_variables" => {
        "name" => "John",
        "order_id" => "ORD-001"
      }
    },
    {
      "recipient" => "+14155555678",
      "template_variables" => {
        "name" => "Jane",
        "order_id" => "ORD-002"
      }
    }
  ]
)

puts result.added      # 2
puts result.duplicates # 0
puts result.invalid    # 0

List Broadcast Contacts

result = client.broadcasts.contacts.list(
  broadcast_id: "brd_abc123",
  status: "pending",
  limit: 100
)

result.items.each do |contact|
  puts "#{contact.recipient} #{contact.status}"
end

Remove Contact

client.broadcasts.contacts.remove(
  broadcast_id: "brd_abc123",
  contact_id: "bcon_xyz789"
)

Send Broadcast

Start sending immediately:
result = client.broadcasts.send_broadcast(
  broadcast_id: "brd_abc123"
)

puts result.broadcast.status # sending
Schedule for later:
result = client.broadcasts.send_broadcast(
  broadcast_id: "brd_abc123",
  scheduled_at: "2024-01-15T10:00:00Z"
)

puts result.broadcast.status # scheduled

Reschedule Broadcast

Change the scheduled time for a broadcast in scheduled status:
result = client.broadcasts.reschedule(
  broadcast_id: "brd_abc123",
  scheduled_at: "2024-01-16T14:00:00Z"
)

puts result.broadcast.scheduled_at # 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:
result = client.broadcasts.progress(broadcast_id: "brd_abc123")

puts result.status                  # sending
puts result.total                   # 5000
puts result.delivered               # 2350
puts result.failed                  # 50
puts result.percent_complete        # 48.0
puts result.estimated_completion_at

Cancel Broadcast

result = client.broadcasts.cancel(broadcast_id: "brd_abc123")

puts 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:
client.broadcasts.delete(broadcast_id: "brd_abc123")