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."
)

print(result.broadcast.id)      # brd_xxx
print(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")

print(result.broadcast.name)
print(result.broadcast.status)
print(result.broadcast.total_contacts)

List Broadcasts

result = client.broadcasts.list()
for broadcast in result.items:
    print(broadcast.id, broadcast.name, broadcast.status)

# 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"
            }
        }
    ]
)

print(result.added)      # 2
print(result.duplicates) # 0
print(result.invalid)    # 0

List Broadcast Contacts

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

for contact in result.items:
    print(contact.recipient, contact.status)

Remove Contact

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

Send Broadcast

Start sending immediately:
result = client.broadcasts.send(broadcast_id="brd_abc123")
print(result.broadcast.status)  # sending
Schedule for later:
result = client.broadcasts.send(
    broadcast_id="brd_abc123",
    scheduled_at="2024-01-15T10:00:00Z"
)
print(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"
)
print(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")

print(result.status)            # sending
print(result.total)             # 5000
print(result.delivered)         # 2350
print(result.failed)            # 50
print(result.percent_complete)  # 48.0
print(result.estimated_completion_at)

Cancel Broadcast

result = client.broadcasts.cancel(broadcast_id="brd_abc123")
print(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")

Async Usage

import asyncio
from zavudev import AsyncZavudev

async def main():
    client = AsyncZavudev()

    result = await client.broadcasts.create(
        name="Async Campaign",
        channel="sms",
        text="Hello {{name}}!"
    )
    print(result.broadcast.id)

asyncio.run(main())