Skip to content
DashboardGet API key

Create broadcast

View .md
POST

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

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Body

application/json

  • namestringrequired

    Name of the broadcast campaign.

  • channelstringrequired

    Broadcast delivery channel. Use 'smart' for per-contact intelligent routing.

    One ofsmartsmssms_onewaywhatsapptelegramemail
  • messageTypestring

    Type of message for broadcast.

    One oftextimagevideoaudiodocumenttemplate
    Defaulttext
  • textstring

    Text content or caption. Supports template variables: {{name}}, {{1}}, etc.

  • contentobject

    Content for non-text broadcast message types.

    8 properties
    • mediaUrlstring

      URL of the media file.

    • mediaIdstring

      Media ID if already uploaded.

    • mimeTypestring

      MIME type of the media.

    • filenamestring

      Filename for documents.

    • templateIdstring

      Template ID for template messages.

    • templateVariablesobject

      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.

      1 properties
      • {key}string
    • templateButtonVariablesobject

      Default button variables for dynamic URL/OTP buttons. Keys are the button index (0, 1, 2). Per-contact values override these.

      1 properties
      • {key}string
    • templateHeaderVariablesobject

      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.

      1 properties
      • {key}string
  • senderIdstring

    Sender profile ID. Uses default sender if omitted.

  • emailSubjectstring

    Email subject line. Required for email broadcasts.

  • emailHtmlBodystring

    HTML body for email broadcasts.

  • scheduledAtstring<date-time>

    Schedule the broadcast for future delivery.

  • metadataobject
    1 properties
    • {key}string
  • idempotencyKeystring

    Idempotency key to prevent duplicate broadcasts.

Responses

201Broadcast created.
  • broadcastobjectrequired
    26 properties
    • idstringrequired
    • namestringrequired
    • statusstringrequired

      Current status of the broadcast. pending_review: in the automated content review. pending_admin_review: the automated review passed and it waits for a person, which is where every channel but a WhatsApp broadcast on an approved template goes. rejected: the review refused it; edit it and retry the review, or escalate. scheduled and sending follow approval.

      One ofdraftpending_reviewpending_admin_reviewapprovedrejectedescalatedrejected_finalscheduledsendingpausedcompletedcancelledfailed
    • channelstringrequired

      Broadcast delivery channel. Use 'smart' for per-contact intelligent routing.

      One ofsmartsmssms_onewaywhatsapptelegramemail
    • messageTypestringrequired

      Type of message for broadcast.

      One oftextimagevideoaudiodocumenttemplate
    • textstring
    • contentobject

      Content for non-text broadcast message types.

      8 properties
      • mediaUrlstring

        URL of the media file.

      • mediaIdstring

        Media ID if already uploaded.

      • mimeTypestring

        MIME type of the media.

      • filenamestring

        Filename for documents.

      • templateIdstring

        Template ID for template messages.

      • templateVariablesobject

        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.

        1 properties
        • {key}string
      • templateButtonVariablesobject

        Default button variables for dynamic URL/OTP buttons. Keys are the button index (0, 1, 2). Per-contact values override these.

        1 properties
        • {key}string
      • templateHeaderVariablesobject

        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.

        1 properties
        • {key}string
    • senderIdstring
    • emailSubjectstring
    • totalContactsintegerrequired

      Total number of contacts in the broadcast.

    • pendingCountinteger
    • sendingCountinteger
    • sentCountinteger

      Recipients whose message the provider accepted, without a confirmed delivery yet. Channels that never report delivery keep their recipients here.

    • deliveredCountinteger

      Recipients with confirmed delivery to the device.

    • failedCountinteger
    • estimatedCostnumbernullable

      Estimated total cost in USD.

    • reservedAmountnumbernullable

      Amount reserved from balance in USD.

    • actualCostnumbernullable

      Actual cost so far in USD.

    • scheduledAtstring<date-time>
    • startedAtstring<date-time>
    • completedAtstring<date-time>
    • metadataobject
      1 properties
      • {key}string
    • createdAtstring<date-time>required
    • updatedAtstring<date-time>
    • reviewResultobjectnullable

      AI content review result.

      5 properties
      • scorenumber

        Content safety score from 0.0 to 1.0, where 1.0 is completely safe.

      • categoriesstring[]

        Policy categories violated, if any.

      • reasoningstring

        Explanation of the review decision.

      • reviewedAtstring<date-time>
      • flaggedContentstring[]nullable

        Problematic text fragments, if any.

    • reviewAttemptsintegernullable

      Number of review attempts (max 3).

400Invalid request.
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject
404The `senderId` or `content.templateId` names no sender or template in this project (`not_found`).
  • codestringrequired
  • messagestringrequired
  • detailsobject
409Idempotency conflict (broadcast already exists).
  • broadcastobjectrequired
    26 properties
    • idstringrequired
    • namestringrequired
    • statusstringrequired

      Current status of the broadcast. pending_review: in the automated content review. pending_admin_review: the automated review passed and it waits for a person, which is where every channel but a WhatsApp broadcast on an approved template goes. rejected: the review refused it; edit it and retry the review, or escalate. scheduled and sending follow approval.

      One ofdraftpending_reviewpending_admin_reviewapprovedrejectedescalatedrejected_finalscheduledsendingpausedcompletedcancelledfailed
    • channelstringrequired

      Broadcast delivery channel. Use 'smart' for per-contact intelligent routing.

      One ofsmartsmssms_onewaywhatsapptelegramemail
    • messageTypestringrequired

      Type of message for broadcast.

      One oftextimagevideoaudiodocumenttemplate
    • textstring
    • contentobject

      Content for non-text broadcast message types.

      8 properties
      • mediaUrlstring

        URL of the media file.

      • mediaIdstring

        Media ID if already uploaded.

      • mimeTypestring

        MIME type of the media.

      • filenamestring

        Filename for documents.

      • templateIdstring

        Template ID for template messages.

      • templateVariablesobject

        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.

        1 properties
        • {key}string
      • templateButtonVariablesobject

        Default button variables for dynamic URL/OTP buttons. Keys are the button index (0, 1, 2). Per-contact values override these.

        1 properties
        • {key}string
      • templateHeaderVariablesobject

        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.

        1 properties
        • {key}string
    • senderIdstring
    • emailSubjectstring
    • totalContactsintegerrequired

      Total number of contacts in the broadcast.

    • pendingCountinteger
    • sendingCountinteger
    • sentCountinteger

      Recipients whose message the provider accepted, without a confirmed delivery yet. Channels that never report delivery keep their recipients here.

    • deliveredCountinteger

      Recipients with confirmed delivery to the device.

    • failedCountinteger
    • estimatedCostnumbernullable

      Estimated total cost in USD.

    • reservedAmountnumbernullable

      Amount reserved from balance in USD.

    • actualCostnumbernullable

      Actual cost so far in USD.

    • scheduledAtstring<date-time>
    • startedAtstring<date-time>
    • completedAtstring<date-time>
    • metadataobject
      1 properties
      • {key}string
    • createdAtstring<date-time>required
    • updatedAtstring<date-time>
    • reviewResultobjectnullable

      AI content review result.

      5 properties
      • scorenumber

        Content safety score from 0.0 to 1.0, where 1.0 is completely safe.

      • categoriesstring[]

        Policy categories violated, if any.

      • reasoningstring

        Explanation of the review decision.

      • reviewedAtstring<date-time>
      • flaggedContentstring[]nullable

        Problematic text fragments, if any.

    • reviewAttemptsintegernullable

      Number of review attempts (max 3).