How campaigns work
Learn how a campaign moves from draft to completed, what it checks before each send, and which events report it.
A campaign sends paced, safety-checked WhatsApp messages from the Numbers in one project to a list of recipients. It is the only bulk sending path in Polymorfa. Every message passes the checks on this page, and every state change is reported by a status on the campaign and its recipients and by a webhook event.
- Content: one approved template, up to 10 composed messages, or an experiment such as an A/B test.
- Recipients: inline phone numbers, an audience, or a segment, each with its own template variables.
- Sending Numbers: the connected Numbers in the project whose tier includes Campaigns. A campaign sends through one sending type: linked-device, Cloud API or test numbers.
- Delivery settings: pacing, per-Number caps, a send window and retries.
Requirements#
Campaigns send only from Numbers on a Number tier that includes Campaigns. In the current catalog that is Pro; Free and Standard do not include Campaigns. The rule applies to test numbers too.
You can create and edit a draft on any tier. Launch checks every sending Number again, and a running campaign pauses when its Numbers lose Campaigns. See Campaign safety checks.
Credentials:
| Surface | Path | Credential |
|---|---|---|
| Messaging API | /messaging/projects/{projectSlug}/campaigns | Project token for that project |
| Platform API | /platform/campaigns | Team key with projectId, or a project token for its own project |
Reading needs campaigns:read. Creating, launching, rescheduling, pausing, resuming, stopping and deleting need campaigns:manage. Audiences, segments, profiles and the opt-out list belong to the team and need a team key.
Lifecycle#
Draft
A new campaign is a
draft. Change its content, recipients, sending Numbers and schedule, and send a test to your own phone. Nothing is sent to recipients.Launch
Launch runs the launch checks below. When they pass, Polymorfa copies the audience into the campaign, skips numbers on the team's opt-out list and sets
recipientCount. A launch over your team's approval threshold waits for an owner or admin instead; see Require approval for large sends.Scheduled
A campaign launched with a future
scheduledAtwaits for that time. Its recipients are already fixed. The Console labels it Scheduled, and the API still reportsdraftuntil sending starts. Move the start with reschedule.Running
The campaign sends to each recipient in queue order, at its pace, from the Numbers that can send at that moment.
Finished
The campaign is
completedwhen every recipient has resolved and no message is waiting. It isfailedwhen every recipient settled as failed. Archive a finished campaign to keep its history marked as archived.
Campaign statuses#
| Status | Meaning | What you can do |
|---|---|---|
draft | Not launched, or launched and waiting for its scheduled start | Edit, test, launch, reschedule a scheduled launch, stop, delete an unscheduled draft |
running | Sending | Pause, stop |
paused | Sending is held, by you or by a check | Resume, stop, edit the send window or frequency cap |
cancelling | A stop was accepted and sends already in progress are finishing | Wait |
cancelled | Stopped; recipients not yet sent were skipped | Archive, delete |
completed | Every recipient resolved | Archive, delete, retarget its recipients |
failed | Every recipient settled as failed | Archive, delete |
archived | A finished campaign you archived | Delete |
Stop is never blocked by a suspension or a lost tier entitlement, so a campaign a check paused can always be stopped. A campaign with no active delivery run cannot be paused or resumed; stop it, duplicate it and launch the copy.
Recipient statuses#
| Status | Meaning |
|---|---|
queued | Waiting to be sent, including outside the send window or while the campaign is paused |
sending | A send is in progress |
sent | WhatsApp accepted the first message |
delivered | The recipient's device confirmed delivery |
read | The recipient opened the message |
failed | The send failed after every attempt |
skipped | Never attempted, such as an opt-out, a cold hold or a stopped campaign |
failureReason gives the stable reason a recipient was skipped or failed. See Failure reasons.
Checks before each send#
Launch checks the campaign once. Polymorfa then checks each recipient again when its message is about to be sent, so a change after launch still applies.
| Check | At launch | At send time |
|---|---|---|
| Tier includes Campaigns | Every pinned Number, or at least one Number in the project when none are pinned | The campaign pauses if its Numbers lose Campaigns |
| Connection and sending type | Pinned Numbers are connected and share one sending type | A disconnected Number leaves the pool until it is ready |
| Throughput | Requested pacing is within its ceiling | The campaign runs at the lower of its rate and any restriction's rate |
| Content and variables | The template is complete, and every variable has a value or fallback | Each message is checked again; no message is sent with an empty variable |
| Opt-out list | Opted-out recipients are skipped | An opted-out number is never claimed, even if it opted out after launch |
| Contact history | A recipient who never wrote to the sending Number is held by default | |
| Warm-up and caps | A new Number's daily cap ramps up; recipients over a cap wait for the next window | |
| Frequency cap (requires access) | Messages over the team or campaign cap are skipped |
Every campaign send also uses jittered pacing and a typing indicator before each text message. The exact rules, limits and error codes are in Campaign safety checks.
Holds are not failures#
A recipient a check holds back is skipped or retried, never counted as a delivery failure. failedCount counts sends WhatsApp refused, not sends Polymorfa never made.
| What happened | The recipient | The campaign |
|---|---|---|
| Opted out, or never wrote first while cold sends are held | skipped, never attempted | Keeps running |
| The sending Number is paced or reached a cap | Queued again, no attempt spent | Keeps running |
| No Number can pass a check, such as a lost tier or a suspension | Left queued, attempt given back | Pauses |
Pausing#
You pause a campaign to hold it. Sends already in progress finish, and the remaining recipients wait. Resume runs the same checks as before the pause.
Polymorfa pauses a campaign for you when no sending Number can clear a check, instead of failing recipients one at a time. The campaign.paused event then carries a reason and one of these codes:
code | Cause |
|---|---|
campaigns_not_entitled | No sending Number is on a tier with Campaigns |
bansafe_team_suspended | Every Number in the team is suspended |
bansafe_suspended | Every Number the campaign sends from is suspended |
campaign_throughput_capped | The requested throughput is above the Numbers' ceiling |
invalid_parameter | A selected Number left the project, or the selection now mixes sending types |
hybrid_campaign_unsupported | The campaign sends from a Hybrid Link Number |
blocked_by_safety | Another safety check on the sending Numbers stopped the campaign |
number_quality_dropped | A Cloud API Number's quality rating dropped while the campaign ran |
messaging_limit_dropped | WhatsApp lowered a Cloud API Number's messaging limit |
Fix the cause, then resume. A campaign that uses an A/B test, weighted variations, drip steps, a segment or a frequency cap also pauses when your team loses access to that beta.
Events#
Subscribe a project webhook to the campaign.* events to follow a campaign without polling. Payloads and delivery rules are in Campaign events.
| Event | Sent when |
|---|---|
campaign.launched | The campaign begins sending |
campaign.rescheduled | The start of a scheduled campaign moved |
campaign.paused | The campaign stopped sending, with reason and code for an automatic pause |
campaign.resumed | A paused campaign sends again |
campaign.stopped | A stop settled and the campaign is cancelled |
campaign.completed | Every recipient resolved, with the final counts |
campaign.failed | Every recipient failed (reason all_recipients_failed) |
campaign.recipient_sent | A message was sent to a recipient, one event per message |
campaign.recipient_failed | A message failed after every attempt |
campaign.recipient_skipped | A recipient will not receive a message |
campaign.cold_blocked | A recipient was held because they never wrote first |
campaign.throttled | Sending was paced back this pass |
campaign.cap_reached | A sending Number reached its hourly, daily or new-chat cap |
campaign.recipient_delivered | First delivery receipt (requires access) |
campaign.recipient_read | First read receipt (requires access) |
campaign.recipient_replied | First attributed reply (requires access) |
campaign.recipient_link_opened | First open of a tracked link (requires access) |
The Platform API also lists a campaign's history with API List campaign events: launched, rescheduled, paused, resumed, cancelled, completed and failed, most recent first. Team members can choose email notices for completed and failed campaigns in My notifications; pausing or stopping a campaign sends no notice.
Test numbers#
Test numbers can send campaigns when their tier includes Campaigns. A test number reaches only other test numbers in the same project, so every recipient of a test-number campaign must be one of them. Weighted message variations do not send from test numbers. See Test numbers.