Skip to content

Templates

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.

  • An Active or Restricted WhatsApp connection (see 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.
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)
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; an action that does not apply to the current status returns 409 campaign_invalid_state.

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

Janela do terminal
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.

Every template parameter needs a source. A missing one → 422 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).

Download the sample CSV to get started:

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:

Janela do terminal
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.

Janela do terminal
curl https://api.messajo.com/v1/campaigns/cmp_.../recipients \
-H "Authorization: Bearer $MESSAJO_API_KEY" \
-F "[email protected]" -F "to_column=to"

The ceiling is 100,000 recipients per campaign (422 campaign_too_many_recipients).

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.

Janela do terminal
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" }'
  • 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.

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

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.

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