# 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
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",
});
```

```bash
curl -X POST https://api.zavu.dev/v1/broadcasts \
  -H "Authorization: Bearer $ZAVUDEV_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
{
  "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
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
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
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%",
    },
  },
});
```

> **Info:**
> Per-contact template variables can override broadcast-level defaults when adding contacts.

### WhatsApp Media Broadcast

```typescript
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
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: `
    <h2>Hello {{name}}!</h2>
    <p>Here are this month's highlights...</p>
  `,
});
```

## 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
// 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.contacts.add(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
const broadcast = await zavu.broadcasts.create({
  name: "Support Alert",
  channel: "sms",
  text: "System maintenance scheduled for tonight.",
  senderId: "snd_support123",
});
```

```bash
curl -X POST https://api.zavu.dev/v1/broadcasts \
  -H "Authorization: Bearer $ZAVUDEV_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
await zavu.broadcasts.update(broadcast.id, {
  name: "Updated Campaign Name",
  text: "Updated message content",
});
```

> **Warning:**
> 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
await zavu.broadcasts.delete(broadcast.id);
```

> **Warning:**
> 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
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

- [Adding Contacts](https://www.zavu.dev/docs/guides/broadcasts/adding-contacts): Learn how to add recipients to your broadcast