Campaigns
Broadcast an approved template to an audience — now, later or on a schedule — with live stats.
- GET
/v1/campaignsList campaignscampaigns:read - POST
/v1/campaignsCreate a draft (or launch with launch: true)campaigns:write - POST
/v1/campaigns/estimateRecipients, exclusions, indicative costcampaigns:read - GET
/v1/campaigns/{id}campaigns:read - PATCH
/v1/campaigns/{id}Draft or scheduled only; returns it to draftcampaigns:write - DELETE
/v1/campaigns/{id}Not while sending or pausedcampaigns:write - POST
/v1/campaigns/{id}/duplicateCopy as a new draftcampaigns:write - POST
/v1/campaigns/{id}/launchcampaigns:launch - POST
/v1/campaigns/{id}/pausecampaigns:launch - POST
/v1/campaigns/{id}/resumecampaigns:launch - POST
/v1/campaigns/{id}/cancelcampaigns:launch - GET
/v1/campaigns/{id}/reportDelivery funnel and top errorscampaigns:read
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).
namestringrequiredInternal name.phone_number_iduuidrequiredSending number.template_iduuidrequiredAn APPROVED template.audienceobjectrequiredWho to send to — see Audience.variablesobjectoptionalMaps each template parameter to a static value or a contact field — see Personalisation.schedule_typeenumoptionalnow(default) ·at·recurringscheduled_atdatetimeoptionalRequired whenschedule_typeisat; at least 30 seconds ahead.recurrenceobjectoptionalForrecurring— see Recurring campaigns.timezonestringoptionalIANA timezone, e.g.Asia/Kolkata. Defaults to your organization's timezone.throttle_per_minintegeroptionalMax messages per minute, 1–60,000.send_windowobjectoptionale.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_secondsintegeroptionalGive up on a message not delivered within this many seconds (30 – 2,592,000).use_mm_apibooleanoptionalSend marketing templates through Meta's Marketing Messages API.launchbooleanoptionalLaunch immediately after creating.
{
"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
{ "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:
{
"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.
Lifecycle
- launch works from
draft. pause frompreparingorsending; resume frompaused; cancel fromscheduled,preparing,sendingorpaused. Other transitions return422. PATCHworks ondraftandscheduledcampaigns and puts them back indraft— launch again after editing.DELETEworks ondraft,scheduled,completed,cancelledandfailedcampaigns.
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.