Campaigns

A campaign reaches a list of people once, on WhatsApp or by phone. This is the same machinery the console drives: your integration gets everything the console gets, and it is held to everything the console is held to.

Create and launch are two calls #

Deliberately. POST /campaigns produces a draft: it messages nobody. You then evaluate it, which tells you the exact recipient count and every exclusion, and launch it.

The alternative, one call that creates and sends, means a network retry after a timeout could message forty thousand people twice. This shape makes that impossible.

The API can't edit a draft. If a draft is wrong, create a new one; a draft that is never launched sends nothing.

Parameters #

Sending script, capture or call_back_incomplete on a WhatsApp campaign is a 400. A {{variable}} in purpose or script that the audience can't fill, such as {{csv.plan}} on a contact audience, is a 400 with reason: "unknown_variable" and the field.

audience #

Each contact is reached on their phone number, or their WhatsApp id when there's no phone. Contacts who opted out of the channel, people on the opt-out list, duplicates and unusable numbers are removed before the count; evaluate itemises them.

template #

consent #

A launch doesn't need a consent statement. If you send one, it is pinned at launch with the time, the recipient count and a checksum of the exact list, and it can't be changed afterwards. consent_basis on the campaign shows it. See Consent and attestation.

schedule #

Every field is optional. A field you leave out comes from your workspace's campaign settings (the Sending rules page in the console), not from a fixed default.

evaluate reports a quiet_hours finding when your hours were clamped. Anything queued outside the window waits for the next open hour. See Quiet hours.

Creating one #

curl -X POST https://services.amomic.in/api/v1/campaigns \
  -H "Authorization: Bearer $AMOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: amc-renewals-2026-10" \
  -d '{
    "name": "AMC renewals, October",
    "channel": "whatsapp",
    "audience": { "kind": "segment", "tags": ["amc-2026", "split-ac"] },
    "template": {
      "name": "amc_renewal_due",
      "language": "en",
      "variables": ["{{contact.name}}", "31 Oct 2026"]
    },
    "schedule": { "throttle_per_minute": 30, "send_window_start_hour": 10 }
  }'

The campaign object #

Every campaign route except evaluate, recipients and the outcome reports returns this shape:

{
  "campaign_id": "cmp_01JRBA3F6H9K2M5P8R1T4W7Y0C",
  "name": "AMC renewals, October",
  "channel": "whatsapp",
  "type": "whatsapp_broadcast",
  "status": "draft",
  "version": 1,
  "recipients": 0,
  "sent": 0,
  "delivered": 0,
  "read": 0,
  "failed": 0,
  "skipped": 0,
  "excluded": {},
  "consent_basis": null,
  "created_at": "2026-10-14T05:58:31.604127+00:00",
  "launched_at": null,
  "completed_at": null,
  "capture": null
}

Campaign statuses #

Listing and reading campaigns #

Most recently changed first. Returns {"items": [campaign, …], "next_cursor": "…"}. The list includes campaigns an app created for you, such as Duesly reminders. See Pagination.

Returns one campaign, or 404 not_found with Campaign not found.

Check before you send #

Runs the launch checks against the audience as it is right now and returns what would happen, without sending anything or changing the campaign. No body. It works with a campaigns:read key, so a reporting integration can ask "would this launch?" without being able to launch it.

{
  "eligible": 3788,
  "total_rows": 4012,
  "excluded": { "channel_consent_missing": 141, "suppressed": 52, "duplicate_recipient": 19, "invalid_destination": 12 },
  "invalid_rows": [
    { "contact_id": "cnt_01JQZ6H2K5N8Q1S4V7X0A3D6FG", "value": "98450 3127", "reason": "invalid_destination" },
    { "value": "Rhea Kapoor", "reason": "missing_variable", "field": "name" }
  ],
  "sample": [
    { "to": "+919811047352", "name": "Arjun Malhotra", "variables": { "1": "Arjun Malhotra", "2": "31 Oct 2026" } }
  ],
  "findings": [
    {
      "code": "suppressed",
      "severity": "info",
      "message": "52 recipients opted out and were removed.",
      "fix": "Opt-outs are permanent and cannot be overridden from here.",
      "docs": "https://docs.amomic.in/campaigns/sending-rules#opt-outs-and-suppression",
      "count": 52
    }
  ],
  "checksum": "5d2e81c4f0a9…"
}

A severity of block means the launch would be refused; warn and info are things you should know. Two refusals are only checked at launch, not here: channel_dormant and allowance_exhausted. The allowance_spill notice also only appears at launch.

Launching #

curl -X POST https://services.amomic.in/api/v1/campaigns/cmp_01JRBA3F6H9K2M5P8R1T4W7Y0C/launch \
  -H "Authorization: Bearer $AMOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expected_version": 1, "confirm_recipients": 3788}'

Send confirm_recipients from the eligible you got back from evaluate. It's the cheapest protection there is against a segment that grew between the two calls.

A successful launch returns the campaign with status running, or scheduled if start_at is in the future, and fires campaign.launched. Launching a paused campaign resumes it instead; the audience isn't rebuilt.

When a guardrail refuses #

Launch runs its checks in this order, and stops at the first that refuses:

1. The campaign has to be a draft or paused. Otherwise 412 with campaign_frozen.
2. The channel has to still be on your plan. Otherwise 412 with channel_dormant.
3. There has to be plan allowance or prepaid credit left for this channel. Otherwise 412 with allowance_exhausted.
4. Every check evaluate runs. A block finding is a 412 with that finding's code.
5. confirm_recipients, if sent, has to equal the eligible count. Otherwise 409 with version_conflict and details.eligible.
6. expected_version has to match. Otherwise 409 with version_conflict, details.expected_version and details.current_version.

A guardrail refusal looks like this:

{
  "error": {
    "code": "failed_precondition",
    "message": "Template 'amc_renewal_due' is not approved by Meta yet.",
    "details": {
      "reason": "template_not_approved",
      "docs": "https://docs.amomic.in/channels/whatsapp-templates#status",
      "fix": "Wait for approval (usually minutes, sometimes a day), or pick an approved template.",
      "findings": [
        { "code": "template_not_approved", "severity": "block", "message": "Template 'amc_renewal_due' is not approved by Meta yet.", "fix": "Wait for approval (usually minutes, sometimes a day), or pick an approved template.", "docs": "https://docs.amomic.in/channels/whatsapp-templates#status", "count": null }
      ]
    },
    "request_id": "req_01JRBA7J0L3N6Q9S2U5W8Y1B4D",
    "correlation_id": "cor_01JRBA7J0L3N6Q9S2U5W8Y1B4D"
  }
}

details.reason is stable and safe to branch on. error.message and details.fix are written for people and may improve. details.findings is the full list from the checks, so you can show every problem at once rather than one per attempt. The refusals from steps 1–3 carry reason and sometimes docs, but no findings.

The guardrail reasons you can meet at launch are unsupported_channel, channel_not_connected, sender_blocked, audience_empty, audience_too_large (over 50,000), plan_limit (over your plan's recipients per campaign; see Campaign recipients), template_not_found, template_not_approved, template_media_missing and voice_daily_cap. Each is explained in Every refusal, and what it means. There is no request field that switches any of them off.

If your contacts can't be read while the audience is built, the request fails with 502 provider_error. It's safe to retry: nothing was staged.

Controlling a running campaign #

All three take expected_version. pause and cancel also accept an optional reason, up to 300 characters, recorded in the campaign's history.

curl -X POST https://services.amomic.in/api/v1/campaigns/cmp_01JRBA3F6H9K2M5P8R1T4W7Y0C/pause \
  -H "Authorization: Bearer $AMOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expected_version": 3, "reason": "Wrong renewal date in the template"}'

Each returns the campaign with its new version. A running campaign's version moves on its own as sends are recorded, so read the campaign immediately before you pause it.

Resume never duplicates. Every recipient is an individual record claimed before it's sent, so nobody already messaged can be messaged again, by a resume, a retry, or two of your servers calling at once. Something already handed to WhatsApp or already ringing when you pause or cancel can't be recalled.

Per-recipient results #

Most recently changed first. A draft has no recipients yet; they are staged at launch.

{
  "items": [
    {
      "recipient_id": "crp_8e2b47d1f06a93c5b28e41d07f6a",
      "to": "+919811047352",
      "name": "Arjun Malhotra",
      "contact_id": "cnt_01JR9X4C7F2H5K8M1P4S7V0YBD",
      "status": "read",
      "reason": null,
      "message_id": "wamid.HBgMOTE5ODExMDQ3MzUyFQIAERgSMEI4…",
      "sent_at": "2026-10-14T06:10:44.281930+00:00",
      "outcome": null,
      "last_call_id": null
    },
    {
      "recipient_id": "crp_31c9f0e8a74b26d1e5c08f93a2b7",
      "to": "+919702264518",
      "name": "Farhan Qureshi",
      "contact_id": "cnt_01JR2B8E1G4J7L0N3Q6S9U2W5Y",
      "status": "skipped",
      "reason": "weekly_contact_cap",
      "message_id": null,
      "sent_at": null,
      "outcome": null,
      "last_call_id": null
    }
  ],
  "next_cursor": "eyJ1cGRhdGVkX2F0IjoiMjAyNi0xMC0xNFQwNjoxMDo0NC4yODE5MzAr…"
}

The API returns reason only. The provider's own error code and detail are on the campaign's page in the console and in its exports. Every reason is listed in Why someone wasn't reached.

On a call campaign, each item also has last_call_id and outcome: that person's answers, merged across every call made to them. outcome is null until a call to them has been read.

{
  "recipient_id": "crp_7d1e93b0c46f28a5e17d90b3c4f8",
  "to": "+919845031276",
  "name": "Kavya Iyer",
  "contact_id": "cnt_01JRB7M9W2E5K8P3T6Y1V4QZAH",
  "status": "sent",
  "reason": null,
  "message_id": null,
  "sent_at": "2026-10-13T10:42:17.506214+00:00",
  "last_call_id": "call_01JRA4D7F0H3K6M9P2R5T8W1Y4",
  "outcome": {
    "disposition": "completed",
    "goal_met": "yes",
    "success": true,
    "summary": "Confirmed the AMC renewal and chose a Saturday morning service visit.",
    "sentiment": "positive",
    "next_step": "none",
    "fields": { "renew_amc": "yes", "visit_slot": "Saturday morning" },
    "captured": 2,
    "expected": 3,
    "calls": 2,
    "updated_at": "2026-10-13T10:49:02.118000+00:00"
  }
}

calls is how many calls to this person have been read. Two means a first call dropped and a second one finished the job; their answers are merged into this one record.

Outcomes #

A call campaign created with a capture reads every call against it. You get the same report the console's Outcomes tab shows. The capture format and the per-call result are on Call outcomes.

{
  "campaign_id": "cmp_01JRA2C5E8G1J4L7N0Q3S6U9W2",
  "name": "AMC renewal calls, October",
  "status": "running",
  "capture": { "goal": "Renew the AMC and book the service visit", "fields": [ … ], "success": { "field": "renew_amc", "equals": "yes" } },
  "totals": {
    "recipients": 486, "called": 461, "answered": 297, "debriefed": 294,
    "completed": 231, "partial": 36, "gave_answers": 267,
    "success": 204, "success_rate": 0.6869, "completion_rate": 0.7778, "answer_rate": 0.6443,
    "avg_capture": 0.84, "unread": 3
  },
  "funnel": [
    { "key": "recipients", "label": "In the audience", "value": 486 },
    { "key": "called", "label": "Called", "value": 461 },
    { "key": "answered", "label": "Picked up", "value": 297 },
    { "key": "gave_answers", "label": "Gave answers", "value": 267 },
    { "key": "completed", "label": "Completed", "value": 231 },
    { "key": "success", "label": "Success", "value": 204 }
  ],
  "dispositions": [ { "key": "completed", "label": "Completed", "count": 231 }, … ],
  "fields": [
    { "key": "renew_amc", "label": "Renew AMC", "type": "yes_no", "display": "auto", "required": true, "answered": 267, "yes": 204, "no": 63 },
    { "key": "visit_slot", "label": "Visit slot", "type": "choice", "display": "auto", "required": false, "answered": 198,
      "options": [ { "label": "Weekday morning", "count": 52 }, { "label": "Weekday evening", "count": 39 }, { "label": "Saturday morning", "count": 107 } ] }
  ],
  "timeline": [ { "at": "2026-10-13T10:00", "completed": 41, "partial": 7, "other": 22 }, … ]
}

• Rates are fractions from 0 to 1. success_rate and completion_rate are out of the calls that were picked up; answer_rate is out of the calls placed. A rate is null until there is something to divide by, and success is null when the capture has no success rule.
• timeline counts readings by hour when the readings span less than a day and a half, and by day (YYYY-MM-DD) after that.
• avg_capture is the average share of fields answered, from 0 to 1, across the people who picked up.
• unread counts answered calls that haven't been read yet. They're retried automatically.
• Each entry in fields summarises one field in a shape that depends on its type: yes/no counts, options counts, avg/min/max/median and buckets for numbers and ratings, day buckets for dates, and the latest samples for text.
• The report is cached for 15 seconds. It doesn't list individual people; page through /recipients for that.

The console's export: a UTF-8 CSV with one row per person, including people not called yet. Columns are Name, Phone, Email, Outcome, Goal met, Success (when there's a success rule), one column per field labelled as in your capture, then Answers captured, Summary, Next step, Call attempts, Talk time (s), Call ID, and the columns from an uploaded list. It needs campaigns:write, not campaigns:read: the file carries emails and every column of an uploaded list, which the recipients endpoint doesn't. Every download is recorded on the campaign's history against the API key that made it.

Both endpoints return 412 failed_precondition with reason: "not_a_call_campaign" for a WhatsApp campaign.

Failures #

Events #

Subscribe rather than poll:

There is no event for pause, resume or cancel. See Webhooks.

Idempotency #

POST /campaigns honours Idempotency-Key: a retry replays the first result instead of creating a second draft. The other campaign writes don't need one. launch, pause, resume and cancel are guarded by expected_version, so a retry of a call that already worked gets a 409 instead of acting twice. See Idempotency.