> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Creating Broadcasts
> Configure your broadcast message and channel settings
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
```typescript TypeScript theme={null}
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",
});
```
```python Python theme={null}
broadcast = zavu.broadcasts.create(
name="Weekly Newsletter",
channel="sms",
text="This week's top deals are live! Shop now at example.com/deals"
)
```
```ruby Ruby theme={null}
broadcast = client.broadcasts.create(
name: "Weekly Newsletter",
channel: "sms",
text: "This week's top deals are live! Shop now at example.com/deals"
)
```
```go Go theme={null}
broadcast, _ := client.Broadcasts.Create(context.TODO(), zavudev.BroadcastCreateParams{
Name: zavudev.String("Weekly Newsletter"),
Channel: zavudev.String("sms"),
Text: zavudev.String("This week's top deals are live! Shop now at example.com/deals"),
})
```
```php PHP theme={null}
$broadcast = $client->broadcasts->create([
'name' => 'Weekly Newsletter',
'channel' => 'sms',
'text' => "This week's top deals are live! Shop now at example.com/deals",
]);
```
```bash cURL theme={null}
curl -X POST https://api.zavu.dev/v1/broadcasts \
-H "Authorization: Bearer $ZAVU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Weekly Newsletter",
"channel": "sms",
"text": "This week'"'"'s top deals are live! Shop now at example.com/deals"
}'
```
### Response
```json theme={null}
{
"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
| Parameter | Type | Required | Description |
| ---------------- | ------ | ----------- | ------------------------------------------ |
| `name` | string | Yes | Name for identifying this broadcast |
| `channel` | string | Yes | `sms`, `whatsapp`, or `email` |
| `messageType` | string | No | Message type (default: `text`) |
| `text` | string | Conditional | Message body (required for text messages) |
| `content` | object | Conditional | Media/template content for rich messages |
| `subject` | string | Conditional | Email subject (required for email channel) |
| `htmlBody` | string | No | HTML body for email messages |
| `scheduledAt` | string | No | ISO 8601 datetime for scheduled delivery |
| `metadata` | object | No | Custom key-value pairs |
| `idempotencyKey` | string | No | Unique key to prevent duplicates |
## Channel-Specific Examples
### SMS Broadcast
```typescript theme={null}
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
```typescript theme={null}
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:
```typescript theme={null}
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
```typescript theme={null}
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
```typescript theme={null}
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: `
Hello {{name}}!
Here are this month's highlights...
`,
});
```
## 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
```typescript theme={null}
// 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:
```typescript TypeScript theme={null}
const broadcast = await zavu.broadcasts.create({
name: "Support Alert",
channel: "sms",
text: "System maintenance scheduled for tonight.",
senderId: "snd_support123",
});
```
```python Python theme={null}
broadcast = zavu.broadcasts.create(
name="Support Alert",
channel="sms",
text="System maintenance scheduled for tonight.",
sender_id="snd_support123"
)
```
```ruby Ruby theme={null}
broadcast = client.broadcasts.create(
name: "Support Alert",
channel: "sms",
text: "System maintenance scheduled for tonight.",
sender_id: "snd_support123"
)
```
```go Go theme={null}
broadcast, _ := client.Broadcasts.Create(context.TODO(), zavudev.BroadcastCreateParams{
Name: zavudev.String("Support Alert"),
Channel: zavudev.String("sms"),
Text: zavudev.String("System maintenance scheduled for tonight."),
SenderID: zavudev.String("snd_support123"),
})
```
```php PHP theme={null}
$broadcast = $client->broadcasts->create([
'name' => 'Support Alert',
'channel' => 'sms',
'text' => 'System maintenance scheduled for tonight.',
'senderId' => 'snd_support123',
]);
```
```bash cURL theme={null}
curl -X POST https://api.zavu.dev/v1/broadcasts \
-H "Authorization: Bearer $ZAVU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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:
```typescript theme={null}
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:
```typescript theme={null}
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:
```typescript theme={null}
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
Learn how to add recipients to your broadcast