Skip to content

Campaigns

Broadcast an approved template to an audience — now, later or on a schedule — with live stats.

Create a campaign

A new campaign is a draft until you launch it with POST /v1/campaigns/{id}/launch — or pass "launch": true to create and launch in one call (this also needs campaigns:launch).

Body parameters
  • namestringrequired
    Internal name.
  • phone_number_iduuidrequired
    Sending number.
  • template_iduuidrequired
    An APPROVED template.
  • audienceobjectrequired
    Who to send to — see Audience.
  • variablesobjectoptional
    Maps each template parameter to a static value or a contact field — see Personalisation.
  • schedule_typeenumoptional
    now (default) · at · recurring
  • scheduled_atdatetimeoptional
    Required when schedule_type is at; at least 30 seconds ahead.
  • recurrenceobjectoptional
    For recurring — see Recurring campaigns.
  • timezonestringoptional
    IANA timezone, e.g. Asia/Kolkata. Defaults to your organization's timezone.
  • throttle_per_minintegeroptional
    Max messages per minute, 1–60,000.
  • send_windowobjectoptional
    e.g. { "start": "09:00", "end": "21:00" } in the campaign timezone; sending pauses outside it. Overnight windows such as 21:00–06:00 work.
  • ttl_secondsintegeroptional
    Give up on a message not delivered within this many seconds (30 – 2,592,000).
  • use_mm_apibooleanoptional
    Send marketing templates through Meta's Marketing Messages API.
  • launchbooleanoptional
    Launch immediately after creating.
POST /v1/campaigns
{
  "name": "Festive sale — VIPs",
  "phone_number_id": "1c2d…",
  "template_id": "3c7d…",
  "audience": { "segments": ["5e6f…"], "tags": ["7f3a…"], "exclude_tags": ["9a1b…"] },
  "variables": {
    "body.1": { "source": "first_name", "fallback": "there" },
    "body.2": { "source": "attribute", "key": "city", "fallback": "your city" },
    "button.0": { "source": "static", "value": "FESTIVE30" }
  },
  "schedule_type": "at",
  "scheduled_at": "2026-11-14T04:30:00Z",
  "timezone": "Asia/Kolkata",
  "throttle_per_min": 2000,
  "send_window": { "start": "09:00", "end": "21:00" }
}

Audience

The audience is the union of lists, segments, tags and contact_ids (all arrays of ids), minus anyone with an exclude_tags tag. Use { "all_contacts": true } to send to everyone. Blocked contacts and contacts without a WhatsApp address are always left out, and opted-out contacts are left out of marketing campaigns.

Personalisation

Each entry in variables has a source: static (uses value), name, first_name, phone or attribute (uses key). fallback is used when the contact field is empty; a recipient with an empty field and no fallback is skipped and counted in stats.skipped.

Recurring campaigns

recurrence
{ "frequency": "weekly", "weekdays": [1, 4], "time": "10:00" }

frequency is daily, weekly or monthly. time is HH:MM in the campaign timezone. For weekly, weekdays uses 1 = Monday … 7 = Sunday; for monthly, set monthday (1–31).

Estimate before launch

Send template_id and audience to see who would receive the campaign:

POST /v1/campaigns/estimate → 200
{
  "recipients": 48210,
  "audience_total": 49414,
  "excluded": { "opted_out": 1204, "us_marketing": 0, "blocked": 0, "no_address": 0 },
  "estimated_cost": { "currency": "INR", "amount": 50138.4, "note": "All-inclusive price for delivered messages, before GST. Undelivered messages are free." },
  "wallet": { "mode": "platform_fee", "balance": 62000.0, "estimated_total": 50138.4, "sufficient": true },
  "messaging_limit": "TIER_100K",
  "plan": { "messages_month": -1, "used": 18240 },
  "warnings": []
}

us_marketing counts US numbers, which WhatsApp doesn't allow marketing templates to reach.

Messaging limits
WhatsApp limits how many unique people a business can message in a rolling 24 hours. If the audience is larger than your limit, the estimate returns a warning — recipients beyond the limit may fail until it resets or grows. Split very large sends or schedule them across days.

Lifecycle

StatusMeaning
draftCreated, not launched; editable
scheduledWill start at scheduled_at or the next recurrence; editable
preparingBuilding the recipient list
sendingSending
pausedPaused; resume to continue
completedAll recipients processed
cancelledStopped; remaining recipients skipped
failedCouldn't run — see last_error
  • launch works from draft. pause from preparing or sending; resume from paused; cancel from scheduled, preparing, sending or paused. Other transitions return 422.
  • PATCH works on draft and scheduled campaigns and puts them back in draft — launch again after editing.
  • DELETE works on draft, scheduled, completed, cancelled and failed campaigns.

Report

GET /v1/campaigns/{id}/report
{
  "campaign": { "id": "…", "name": "Festive sale — VIPs", "status": "completed", "…": "…" },
  "stats": { "total": 48210, "queued": 0, "sent": 48210, "delivered": 46480,
             "read": 34612, "failed": 1730, "cancelled": 0, "replied": 2210, "skipped": 0 },
  "errors": [
    { "code": 131049, "title": "Per-user marketing limit reached", "detail": "…", "count": 1288 },
    { "code": 131026, "title": "Message undeliverable", "detail": "…", "count": 442 }
  ]
}

Counts are cumulative: a read message also counts as sent and delivered. replied counts recipients who wrote back within 8 days. Subscribe to the campaign.completed webhook to hear when a campaign finishes.

Something unclear or missing on this page? Tell us at contact@swastik.ai