Skip to content
Shortcut: /, ⌘K or Ctrl+K

How campaigns work

Learn how a campaign moves from draft to completed, what it checks before each send, and which events report it.

View as Markdown

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:

SurfacePathCredential
Messaging API/messaging/projects/{projectSlug}/campaignsProject token for that project
Platform API/platform/campaignsTeam 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#

  1. 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.

  2. 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.

  3. Scheduled

    A campaign launched with a future scheduledAt waits for that time. Its recipients are already fixed. The Console labels it Scheduled, and the API still reports draft until sending starts. Move the start with reschedule.

  4. Running

    The campaign sends to each recipient in queue order, at its pace, from the Numbers that can send at that moment.

  5. Finished

    The campaign is completed when every recipient has resolved and no message is waiting. It is failed when every recipient settled as failed. Archive a finished campaign to keep its history marked as archived.

Campaign statuses#

StatusMeaningWhat you can do
draftNot launched, or launched and waiting for its scheduled startEdit, test, launch, reschedule a scheduled launch, stop, delete an unscheduled draft
runningSendingPause, stop
pausedSending is held, by you or by a checkResume, stop, edit the send window or frequency cap
cancellingA stop was accepted and sends already in progress are finishingWait
cancelledStopped; recipients not yet sent were skippedArchive, delete
completedEvery recipient resolvedArchive, delete, retarget its recipients
failedEvery recipient settled as failedArchive, delete
archivedA finished campaign you archivedDelete

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#

StatusMeaning
queuedWaiting to be sent, including outside the send window or while the campaign is paused
sendingA send is in progress
sentWhatsApp accepted the first message
deliveredThe recipient's device confirmed delivery
readThe recipient opened the message
failedThe send failed after every attempt
skippedNever 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.

CheckAt launchAt send time
Tier includes CampaignsEvery pinned Number, or at least one Number in the project when none are pinnedThe campaign pauses if its Numbers lose Campaigns
Connection and sending typePinned Numbers are connected and share one sending typeA disconnected Number leaves the pool until it is ready
ThroughputRequested pacing is within its ceilingThe campaign runs at the lower of its rate and any restriction's rate
Content and variablesThe template is complete, and every variable has a value or fallbackEach message is checked again; no message is sent with an empty variable
Opt-out listOpted-out recipients are skippedAn opted-out number is never claimed, even if it opted out after launch
Contact historyA recipient who never wrote to the sending Number is held by default
Warm-up and capsA 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 happenedThe recipientThe campaign
Opted out, or never wrote first while cold sends are heldskipped, never attemptedKeeps running
The sending Number is paced or reached a capQueued again, no attempt spentKeeps running
No Number can pass a check, such as a lost tier or a suspensionLeft queued, attempt given backPauses

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:

codeCause
campaigns_not_entitledNo sending Number is on a tier with Campaigns
bansafe_team_suspendedEvery Number in the team is suspended
bansafe_suspendedEvery Number the campaign sends from is suspended
campaign_throughput_cappedThe requested throughput is above the Numbers' ceiling
invalid_parameterA selected Number left the project, or the selection now mixes sending types
hybrid_campaign_unsupportedThe campaign sends from a Hybrid Link Number
blocked_by_safetyAnother safety check on the sending Numbers stopped the campaign
number_quality_droppedA Cloud API Number's quality rating dropped while the campaign ran
messaging_limit_droppedWhatsApp 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.

EventSent when
campaign.launchedThe campaign begins sending
campaign.rescheduledThe start of a scheduled campaign moved
campaign.pausedThe campaign stopped sending, with reason and code for an automatic pause
campaign.resumedA paused campaign sends again
campaign.stoppedA stop settled and the campaign is cancelled
campaign.completedEvery recipient resolved, with the final counts
campaign.failedEvery recipient failed (reason all_recipients_failed)
campaign.recipient_sentA message was sent to a recipient, one event per message
campaign.recipient_failedA message failed after every attempt
campaign.recipient_skippedA recipient will not receive a message
campaign.cold_blockedA recipient was held because they never wrote first
campaign.throttledSending was paced back this pass
campaign.cap_reachedA sending Number reached its hourly, daily or new-chat cap
campaign.recipient_deliveredFirst delivery receipt (requires access)
campaign.recipient_readFirst read receipt (requires access)
campaign.recipient_repliedFirst attributed reply (requires access)
campaign.recipient_link_openedFirst 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.

See also#