Campaigns — the full life of a campaign, its report and its CSV export
Who this guide is for: customer ADMINISTRATORS who write, approve or review WhatsApp campaigns.
This guide follows a campaign through its whole life as the product actually runs it: the protective refusals you will meet first, approval, sending (with an honest pause), completion, and finally the report and its spreadsheet (CSV) export.
About the evidence. Every campaign, audience row and consent record in the run behind this guide was test data created by the test. No live WhatsApp/Meta message was sent. The sending states advanced over the product's real routes against a throwaway database that was destroyed after the run.
The two guard rails you meet first
1. SMS campaigns are refused — this product sends WhatsApp only
A campaign created with the SMS channel is refused before anything is saved. Nothing is left behind — no campaign, no audience, no draft. At this time campaign sending is WhatsApp-only.
What to do: use the SMS product (sms-ocean) for SMS campaigns; use ConvoTide for WhatsApp campaigns.
2. Check who can approve the campaign
On Basic, the eligible sole verified Customer Owner can approve a WhatsApp campaign they created. For a team campaign, a different current Customer Admin or a teammate with delegated campaign approval must approve it. The approval record is written once and shows who approved. See the owner's guide.
The campaign's life, step by step
- Draft. The campaign exists; nothing sends. Trying to queue recipients while still a draft is refused — the campaign must be scheduled first.
- Scheduled. Once scheduled, a recipient who has agreed to receive messages (consent) is accepted into the queue. A recipient without consent is refused — an honest refusal, not a silent skip. Sending the same request twice does not queue anyone twice: the repeat answers truthfully and changes nothing.
- Sending and completion. After approval and scheduling, the campaign can start sending. For campaigns with lifecycle controls, an authorized operator can pause, resume or select Complete in the campaign detail. Sending can remain on the campaign after its current recipients have delivery outcomes. Use the recipient report to see which messages were read, delivered or failed. The first sending transition records the launch time.
- Editing freezes with the campaign. You can change the schedule while it is a draft. Once sending has started, schedule changes are refused (message: scheduling frozen). A finished campaign never reopens, and a draft can be cancelled from its row in the campaign list.
If you see an error
| What you see | What it means | What to do |
|---|---|---|
| Refusal on SMS-channel campaign creation | ConvoTide campaigns are WhatsApp-only | Use the sms-ocean product for SMS |
| SELF_APPROVAL_FORBIDDEN | This campaign requires a different approver | Ask an eligible Customer Admin or delegated campaign approver |
| APPROVAL_REQUIRED when trying to send | Nobody has approved the campaign yet | Complete approval first |
| Consent refusal when queueing a recipient | That person has not agreed to receive messages | Do not retry; the refusal is correct |
| Scheduling-frozen refusal | Sending has already started | No schedule changes are possible anymore |
| Report refuses a window of 0 or 91+ days | Only 1–90 day windows are valid | Choose a window in that range |
The report: what the numbers are made of
The campaign report shows the campaign's status, audience counters and results, and every number is read from the database — the report never invents a number. An unknown campaign is an honest "not found".
Inside the report:
- The funnel. The overall-success percentage excludes the test seed rows, and the submitted/sent/delivered/read funnel adds up exactly to that denominator.
- Failure reasons. Failed rows show the provider's documented error code; a failure without a code lands in an explicit "unknown" bucket — never blank, never guessed.
- Search. You can search by exact recipient or exact transaction reference; malformed searches are refused with a clear error (422).
- Status filter. Narrows the rows and the total together, and stays inside the one campaign — rows from other campaigns never mix in. An invalid status value is refused (422).
- Paging. Large audiences page through without duplicates; a broken page cursor is refused (400).
The CSV export — audited, and identity-protected
The campaign export writes delivery.csv — a standard spreadsheet format
(RFC 4180), with the campaign id on every row, matching the on-screen rows
exactly. Every export writes exactly one audit record saying the export
happened.
Identity protection shows up here: a member without the "view personal information" permission sees masked identity fields and the CSV export is refused, while an administrator holding that permission can export. If a teammate's download is refused while they can otherwise see the report, this permission — not a fault — is the reason.
One business never sees another's campaigns
A different business's account reading these campaigns, reports and recipient pages sees zero rows of your data. That is enforced in the database itself, verified in the run behind this guide — not just a promise in a document.
What this guide does NOT claim (kept honest)
- Seed acts — what a seed row is and how the report excludes it — are summarized from the report behavior only; no seed-creation journey is documented in this tree.
- Anything after the report — no journey evidence exists for post-report corrections or failure-recovery actions in this tree. The queue and consent sides of the recipient journey are documented by their own carried chapters: the queue journey and the consent gate.
- Live sending — all states advanced against the synthetic test harness; no live WhatsApp/Meta delivery is claimed anywhere.
- Browser screens for these steps are documented in the owner's guide, under its own evidence standing (Chief acceptance open).
Evidence record (kept for honesty). The FULL3747-O14EV lane executed
suite o14-ev3747-s4-campaigns-tpl-dest.pg.test.mjs — 24/24 cases
passed — on the combined candidate checkout (C:/CT-ZC-FULL3747, branch
codex/zcode-full3747), driving the real compiled application over real
loopback HTTP against an ordinary throwaway PostgreSQL 16 cluster (app role
NOBYPASSRLS, row security forced on every table, verified in retained
O14EV-HTTP-ROLE-RLS.json). Verbatim case receipt:
C:/CT-ZC-FULL3747/tools/zcode-integration3723/runtime/evidence/o14ev-s4/O14EV-S4-CAMPAIGNS-TPL-DEST-CASES.json
(suite S4-campaigns-tpl-dest, started 2026-10-25T00:42:42.256Z). Campaign
cases cover matrix rows O09.06, O09.07, O10.01–O10.08; the lane ledger
records 61 of 62 matrix rows executed-green, 1 row (O03.22) carried open —
C:/CT-ZCODE-FULL3747/lane-o14ev-ledger.json. Standing:
local-candidate, test-harness evidence — real routes, real database,
synthetic businesses; Chief acceptance and publication OPEN; no live or
Main-built deployment claimed.