---
title: "Create broadcast"
method: POST
path: "/v1/broadcasts"
---

# Create broadcast

`POST /v1/broadcasts`

Create a new broadcast campaign. Add contacts after creation, then send.

## Request body

- BroadcastCreateRequest
  - `name` string, required — Name of the broadcast campaign.
  - `channel` 'smart' | 'sms' | 'sms_oneway' | 'whatsapp' | 'telegram' | 'email', required — Broadcast delivery channel. Use 'smart' for per-contact intelligent routing.
  - `messageType` 'text' | 'image' | 'video' | 'audio' | 'document' | 'template' — Type of message for broadcast.
  - `text` string — Text content or caption. Supports template variables: {{name}}, {{1}}, etc.
  - `content` BroadcastContent — Content for non-text broadcast message types.
    - `mediaUrl` string — URL of the media file.
    - `mediaId` string — Media ID if already uploaded.
    - `mimeType` string — MIME type of the media.
    - `filename` string — Filename for documents.
    - `templateId` string — Template ID for template messages.
    - `templateVariables` object — Default body variables (can be overridden per contact). Key them to match the template body: by position (`1`, `2`, ...) for positional templates, or by name (e.g. `customer_name`) for named templates. Zavu detects the template's format and sends the correct payload to Meta. Do not mix positional and named keys.
    - `templateButtonVariables` object — Default button variables for dynamic URL/OTP buttons. Keys are the button index (0, 1, 2). Per-contact values override these.
    - `templateHeaderVariables` object — Default value for a text-header variable, keyed by `1` (can be overridden per contact). If omitted, Zavu resolves the header from `templateVariables` by the header placeholder's name.
  - `senderId` string — Sender profile ID. Uses default sender if omitted.
  - `emailSubject` string — Email subject line. Required for email broadcasts.
  - `emailHtmlBody` string — HTML body for email broadcasts.
  - `scheduledAt` string, date-time — Schedule the broadcast for future delivery.
  - `metadata` object
  - `idempotencyKey` string — Idempotency key to prevent duplicate broadcasts.

## Response `201`

Broadcast created.

- BroadcastResponse
  - `broadcast` Broadcast, required
    - `id` string, required
    - `name` string, required
    - `status` 'draft' | 'pending_review' | 'approved' | 'rejected' | 'escalated' | 'rejected_final' | 'scheduled' | 'sending' | 'paused' | 'completed' | 'cancelled' | 'failed', required — Current status of the broadcast.
    - `channel` 'smart' | 'sms' | 'sms_oneway' | 'whatsapp' | 'telegram' | 'email', required — Broadcast delivery channel. Use 'smart' for per-contact intelligent routing.
    - `messageType` 'text' | 'image' | 'video' | 'audio' | 'document' | 'template', required — Type of message for broadcast.
    - `text` string
    - `content` BroadcastContent — Content for non-text broadcast message types.
      - `mediaUrl` string — URL of the media file.
      - `mediaId` string — Media ID if already uploaded.
      - `mimeType` string — MIME type of the media.
      - `filename` string — Filename for documents.
      - `templateId` string — Template ID for template messages.
      - `templateVariables` object — Default body variables (can be overridden per contact). Key them to match the template body: by position (`1`, `2`, ...) for positional templates, or by name (e.g. `customer_name`) for named templates. Zavu detects the template's format and sends the correct payload to Meta. Do not mix positional and named keys.
      - `templateButtonVariables` object — Default button variables for dynamic URL/OTP buttons. Keys are the button index (0, 1, 2). Per-contact values override these.
      - `templateHeaderVariables` object — Default value for a text-header variable, keyed by `1` (can be overridden per contact). If omitted, Zavu resolves the header from `templateVariables` by the header placeholder's name.
    - `senderId` string
    - `emailSubject` string
    - `totalContacts` integer, required — Total number of contacts in the broadcast.
    - `pendingCount` integer
    - `sendingCount` integer
    - `deliveredCount` integer
    - `failedCount` integer
    - `estimatedCost` number, nullable — Estimated total cost in USD.
    - `reservedAmount` number, nullable — Amount reserved from balance in USD.
    - `actualCost` number, nullable — Actual cost so far in USD.
    - `scheduledAt` string, date-time
    - `startedAt` string, date-time
    - `completedAt` string, date-time
    - `metadata` object
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time
    - `reviewResult` object, nullable — AI content review result.
      - `score` number — Content safety score from 0.0 to 1.0, where 1.0 is completely safe.
      - `categories` string[] — Policy categories violated, if any.
      - `reasoning` string — Explanation of the review decision.
      - `reviewedAt` string, date-time
      - `flaggedContent` string[], nullable — Problematic text fragments, if any.
    - `reviewAttempts` integer, nullable — Number of review attempts (max 3).

## Other responses

- `400` — Invalid request.
- `401` — Unauthorized.
- `409` — Idempotency conflict (broadcast already exists).

---

[API](https://skmtc.net/zavudev/apis/zavu-unified-messaging-layer-api.md) · [All operations](https://skmtc.net/zavudev/apis/zavu-unified-messaging-layer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zavudev/zavu-unified-messaging-layer-api/versions/07b87b6ae707/schema)