Campaigns

Schedule WhatsApp marketing blasts to uploaded audiences

What it is

Campaigns is the workspace for scheduled, audience-targeted WhatsApp blasts. It uses two Meta APIs depending on the send’s category:

• MARKETING sends route through the Marketing Messages Lite API — high-volume optimized, opt-in-required, US recipients blocked.
• UTILITY sends route through the standard WhatsApp Cloud API — for transactional/account-related notifications. Different pricing category, fewer geographic restrictions.

You pick the category per send. The recipient receives the same kind of WhatsApp message either way; the difference is server-side routing, billing category, and policy gates.

A campaign has:

• One audience (uploaded as CSV — phone numbers + arbitrary template variables)
• One or more sends scheduled in chronological order (think of them as messages in a drip sequence)
• One WhatsApp number to send from (any active WABA phone number in your org)

Each send fires its assigned template at its scheduled time, to its audience (optionally narrowed by an inbound payload — see Audience Filtering and Lead Events).

Send categories

Category	API routed through	Template category	Typical use	Geographic restrictions
marketing	Marketing Messages Lite (/marketing_messages)	MARKETING	Promotions, announcements, drip campaigns	US blocked; EEA/UK/JP/KR have limited reporting
utility	Cloud API (/messages)	UTILITY	Account notifications, status updates, reminders	Standard Cloud API rules apply (broader geo support)

Pick category per send when adding it to the sequence. The campaign editor only lets you pick templates whose Meta-side category matches the send category — switching the send category clears your template pick.

Why mix them? A common pattern: send 1–3 are MARKETING (engagement push), send 4 is UTILITY (the actual confirmation/receipt with no marketing content). Keeping them in one campaign keeps audience handling consistent without forcing you to spin up a parallel campaign just to swap APIs.

Replies to campaign messages flow back through your existing bot — the bot attached to the chosen WhatsApp number handles conversations as it normally would.

Lifecycle

A campaign moves through these states:

Status	Meaning
draft	Editable. Sequence can be modified. No sends will fire.
scheduled	Locked. Sends will fire at their scheduled times.
paused	Toggled off. Materializer skips this campaign entirely. Reversible — turn back on anytime.
running	At least one send is currently firing.
completed	All sends have fired (or terminally failed). Final state.
cancelled	Permanently stopped. Pending sends won’t fire. Final state.

Sends within a campaign

Each send is a single blast. Per-send config:

• Scheduled time + IANA time zone (DST-aware — the saved UTC instant respects the picked zone’s rules at that exact moment)
• Template — Meta-approved MARKETING-category template (created in WhatsApp Business Manager)
• Audience filter — off (full audience, minus opt-outs) or on (narrowed by inbound webhook payload)

Sends fire one at a time per campaign. Throughput within a single send is rate-limited to your campaign’s max_messages_per_second (default 20 — tune up after a successful dry run). Per-recipient delivery, read, and failure events flow back from Meta’s webhook and are recorded for analytics.

Geographic eligibility

Two policy realities Meta enforces for MARKETING sends, which Campaigns surfaces at upload time:

• US recipients are blocked with error 131049 across all WhatsApp marketing APIs. We mark them ineligible_geo at audience ingest and skip them at send time.
• EEA / UK / Japan / South Korea — sends deliver, but Meta does not return read/click metrics through standard webhooks for these regions. The audience detail page surfaces the affected count so you don’t misread their analytics.

UTILITY sends are not subject to the US block — the Cloud API path doesn’t have that policy gate. If you need to reach US recipients, ensure those sends are categorized utility AND that the template content is genuinely transactional (Meta enforces this on the template approval side).

Opt-outs

When a recipient replies with a STOP-style keyword (stop, unsubscribe, unsub, cancel, end, quit, remove me, opt out, opt-out), an opt-out is recorded for that organization + phone. The materializer skips opted-out numbers on subsequent sends, automatically.

Match is conservative — only when the keyword is the entire message or a leading keyword followed by punctuation. We don’t match phrases like “please don’t stop sending these”.

Opt-outs are per-organization. The same phone replying STOP to org A is not opted out from org B’s campaigns.

Onboarding gates

Before your first send actually goes through:

For MARKETING sends:

• Your WhatsApp Business Account (WABA) must accept the MM Lite Terms of Service in Meta’s App Dashboard. There’s no API to do this on your behalf — manual one-time step per WABA.
• You need at least one approved MARKETING-category template in your WABA.
• For 80k-recipient sends, your WABA needs TIER_100K or higher messaging tier (visible via GET /{phone-number-id}?fields=messaging_limit_tier).
• Recipients must be opted in to receive WhatsApp marketing messages from your business — required by Meta’s marketing message policy. You confirm this at campaign creation time (product_policy flag, sent on every API call).

For UTILITY sends:

• You need at least one approved UTILITY-category template in your WABA.
• No MM Lite ToS or product_policy flag required.
• Standard Cloud API messaging-limit tiers apply.