Skip to content
DashboardGet API key

Create a campaign

View .md
POST

A campaign is a /v1 broadcast; the id works on /v1/broadcasts/{broadcastId}. Runs POST /v1/broadcasts with the sender resolved from from. A repeated idempotencyKey answers 409 conflict with the original in details.campaign. A channel the resolved sender does not carry (smart: no channel at all) is refused at creation with 409 no_channel, as on POST /v2/messages, rather than created and failed at send. from with a channel it does not carry (a sms campaign from: "sms_oneway") is that same 409 no_channel, in the words POST /v2/messages uses (details.connected, and sms vs sms_oneway told apart); channel only picks between senders that share an address, it never makes an existing address 404.

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
  • 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.

  • fromstring

    The address that sends the campaign (GET /v2/channels). The project default when omitted. Resolved like from on POST /v2/messages, with the campaign's channel as the transport (none for smart).

Responses

201Created as `draft`.
  • campaignobjectrequired

    A campaign. The same object as a /v1 broadcast: its id works on /v1/broadcasts/{broadcastId}.

    26 properties
    • idstringrequired
    • namestringrequired
    • statusstringrequired

      Current status of the campaign. 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 campaign on an approved template goes. rejected: the review refused it; edit it and send again, 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
    • 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).

    • fromstringnullable

      The address the campaign is sent from, for its channel (the sender's first address when channel is smart).

400Invalid body (`details.errors`).
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring
403`kyb_required`: `channel: "sms_oneway"` on an account required to verify its business before using one-way SMS, until that verification is approved. One-way SMS needs no verification by default.
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring
404`from` names no address of this project (`details.from`).
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring
409`no_channel`: no `from` and no default, or the sender has no `channel` transport (`details.channel`, `details.connect`, `details.connected`, the same answer as `POST /v2/messages` with that `channel`). `ambiguous_from`, or `conflict` (repeated `idempotencyKey`; the original is in `details.campaign`).
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring