# WhatsApp campaigns

> Approved template + CSV/JSON list + variables + scheduling: how to build, send, monitor and resume a campaign.

A campaign sends **one approved template** to a list of contacts, at the number's pace and within the portfolio's 24-hour tier. It only exists on WhatsApp: Instagram and Messenger do not allow bulk sending.

## Before you start

- An **Active** or **Restricted** WhatsApp connection (see [Connect WhatsApp](/en/connect/whatsapp/)).
- An **Approved** template in the **Marketing** or **Utility** category on that connection.
- An API key with the `send` permission (to create and launch) or a member with the owner, admin or dev role in the panel. The viewer role is read-only.

## Lifecycle

| Status | Meaning |
|---|---|
| `draft` | Draft. Template, variables and recipients can only change here |
| `scheduled` | Scheduled for `scheduled_at` |
| `running` | Sending |
| `waiting_limit` | The portfolio's 24-hour tier ran out; it resumes on its own at `limit_wait_until` |
| `paused` | Paused by someone |
| `auto_paused` | Paused by Messajo to protect the number (see [Pauses](#pauses-and-what-to-do)) |
| `completed` | No recipient left in the queue |
| `canceled` | Canceled; queued recipients become `skipped` |

Name and speed (`rate_limit_mps`) can also change in `scheduled`, `paused` and `auto_paused`. Editing anything else outside a draft returns `409` [`campaign_not_editable`](/en/errors#campaign_not_editable); an action that does not apply to the current status returns `409` [`campaign_invalid_state`](/en/errors#campaign_invalid_state).

## 1. Create the draft

In the panel: **Campaigns → New campaign**, pick the connection and the template. Through the API:

```bash
curl https://api.messajo.com/v1/campaigns \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday",
    "connection_id": "conn_...",
    "template": { "name": "promo_bf", "language": "en_US" },
    "variables": {
      "body": [
        { "contact": "display_name", "default": "there" },
        { "column": "coupon" }
      ]
    }
  }'
```

The response is the campaign in `draft`. A template that is not approved or is not marketing/utility → `422` [`campaign_template_not_approved`](/en/errors#campaign_template_not_approved).

## 2. Map the variables

Every template parameter needs a source. A missing one → `422` [`campaign_template_mapping_invalid`](/en/errors#campaign_template_mapping_invalid), with the parameter in `details`.

| Source | Example | Where the value comes from |
|---|---|---|
| Column | `{ "column": "coupon", "default": "BF10" }` | a CSV column or a key of `variables` in JSON |
| Fixed | `{ "value": "until Sunday" }` | the same text for everyone |
| Contact | `{ "contact": "display_name", "default": "there" }` | the contact's name, when Messajo knows it |

- `body`: a list in the order of `{{1}}`, `{{2}}`… (positional format) or an object by name (`NAMED` format).
- `header`: `{ "params": [...] }` for text, `{ "media_id": "med_..." }` for image, video or document, or `{ "location": {...} }`.
- `buttons`: `[{ "index": 0, "param": {...} }]` for dynamic URL, coupon code and payload.

Use `default` when the column may be empty. Without `default`, the row becomes `invalid` with the reason `missing_variable:<column>`. A value longer than 1024 characters becomes `invalid` (`variable_too_long`).

## 3. Upload the list

Download the [sample CSV](/examples/campaign-example.csv) to get started:

```csv
to,name,coupon
5511999990001,Ana,BF10
+55 (21) 99999-0002,Bruno,
ctc_0193a1b2c3d47e8f9a0b1c2d3e4f5a6b,,BF20
```

- A header row is required. The recipient column is `to` (or another one, with `to_column`); the other columns become variables.
- Separator `,`, `;` or tab. Excel's BOM is accepted.
- The recipient can be a phone number (Messajo strips `+ ( ) - .` and spaces; 8 to 15 digits), a BSUID or the `ctc_…` of a contact in the organization.
- Duplicates are ignored and counted in `rows_duplicate`.

Up to 10,000 recipients per call go in the JSON body, and the import comes back finished:

```bash
curl https://api.messajo.com/v1/campaigns/cmp_.../recipients \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "recipients": [ { "to": "5511999990001", "variables": { "coupon": "BF10" } } ] }'
```

A file (CSV, JSON or NDJSON, up to 20 MiB) goes as `multipart` and returns `202` with the import queued. Follow it at `GET /v1/campaigns/{id}/imports/{import_id}`: the first 100 errors come in `errors` with row, column and code.

```bash
curl https://api.messajo.com/v1/campaigns/cmp_.../recipients \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -F "file=@campaign-example.csv" -F "to_column=to"
```

The ceiling is 100,000 recipients per campaign (`422` [`campaign_too_many_recipients`](/en/errors#campaign_too_many_recipients)).

## 4. Check the preview

`POST /v1/campaigns/{id}/preview` (or the **Preview** step in the panel) shows the first messages already built, with the body and the parameters filled in. Check it before scheduling: a wrong message cannot be taken back.

## 5. Schedule or start now

```bash
curl -X POST https://api.messajo.com/v1/campaigns/cmp_.../schedule \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-11-27T12:00:00Z" }'
```

- `scheduled_at` between 1 minute and 90 days ahead (`422` [`campaign_schedule_invalid`](/en/errors#campaign_schedule_invalid)).
- It needs at least one valid recipient ([`campaign_no_recipients`](/en/errors#campaign_no_recipients)) and no import in progress ([`campaign_import_in_progress`](/en/errors#campaign_import_in_progress)).
- `POST /start` launches now; `POST /unschedule` goes back to draft.

## Speed and the portfolio tier

- **Speed:** by default, 80% of the number's throughput (`send_rate_mps`); the remaining 20% is left for API sends. Adjust it with `rate_limit_mps`, from 1 up to the number's throughput.
- **24-hour tier:** Meta limits how many **unique** contacts receive templates per day (250, 2,000, 10,000, 100,000 or unlimited). The limit belongs to the **portfolio**: all numbers in the same Business share the tier. Messajo stops at 95% of the tier and the campaign moves to `waiting_limit`; when the oldest sends leave the 24-hour window, it resumes on its own.
- A contact with an open service window does not use the tier.
- The counter only sees what goes out through Messajo. If you also send from another tool on the same portfolio, leave some headroom.

`GET /v1/campaigns/{id}` includes `estimate`: valid recipients, effective speed, estimated duration and how much of the tier is left.

## Pauses and what to do

Messajo pauses on its own (`auto_paused`), emails the owners, the admins and whoever created the campaign, and emits `campaign.paused` with `auto: true`. To continue, `POST /resume` (or **Resume** in the panel): resuming accepts the current quality as the new baseline.

| `pause_reason` | Why | What to do |
|---|---|---|
| `quality_low` | The number's quality dropped (or sending became limited) | Review content and list; pushing on lowers the quality and the tier |
| `template_paused` | The template left **Approved** | Wait for it to return to Approved under **Templates** |
| `template_quality_low` | The template's quality dropped | Adjust the template or the list: many people are blocking or reporting |
| `error_rate` | 20% or more failures in the last 100 sends | Download the report and check the codes |
| `marketing_limit` | 10% or more `131049` | See below |
| `spam_limit` | Meta answered `131048` (suspected spam) | Wait a few hours and lower the speed |
| `policy` | Policy block or broken token | Fix it on the connection; it may need a reconnect |
| `connection_not_active` | The connection is not active | Reconnect and resume |
| `spend_cap` | The month's spend cap was reached | Raise the cap in Settings → Costs or wait for the month to roll over, then resume |
| `manual` | Someone paused it | Resume whenever you want |

### 131049 and the 24 hours

[`marketing_limit_reached`](/en/errors#marketing_limit_reached) (`131049`) is Meta holding back marketing for people who already received too much. It is not a problem with the number and retrying right away does not help: the contact only receives again after a period Meta does not disclose (in practice, a day or more). Finish the campaign, wait at least 24 hours and use **Duplicate** with `recipients: "failed"` to send only to those who failed.

## Monitoring and the report

- `GET /v1/campaigns/{id}/recipients?status=failed` lists recipients by status: `pending`, `invalid`, `sending`, `sent`, `delivered`, `read`, `failed`, `unknown`, `skipped`.
- `unknown` is a send that may have gone out (Meta or the process went down midway). Messajo **never** resends blindly; if Meta sends the status later, the recipient is updated.
- `GET /v1/campaigns/{id}/report` returns a CSV with `to`, `contact_id`, `status`, `message_id`, `external_id`, `error_code`, `meta_code`, the dates and the variable columns.
- Delivery statuses keep arriving for up to 72 hours after `completed`.
- Events: `campaign.scheduled`, `campaign.started`, `campaign.paused`, `campaign.resumed`, `campaign.progress` (at most 1 per minute), `campaign.completed` and `campaign.canceled`. Messages carry `campaign: { id, recipient_id }` in `message.sent` and `message.status`. See [Events](/en/webhooks/events/).
