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.
Before you start
Section titled “Before you start”- 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
sendpermission (to create and launch) or a member with the owner, admin or dev role in the panel. The viewer role is read-only.
Lifecycle
Section titled “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) |
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.
1. Create the draft
Section titled “1. Create the draft”In the panel: Campaigns → New campaign, pick the connection and the template. Through the API:
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.
2. Map the variables
Section titled “2. Map the variables”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 (NAMEDformat).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
Section titled “3. Upload the list”Download the sample CSV to get started:
to,name,coupon5511999990001,Ana,BF10+55 (21) 99999-0002,Bruno,ctc_0193a1b2c3d47e8f9a0b1c2d3e4f5a6b,,BF20- A header row is required. The recipient column is
to(or another one, withto_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 thectc_…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:
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.
curl https://api.messajo.com/v1/campaigns/cmp_.../recipients \ -H "Authorization: Bearer $MESSAJO_API_KEY" \The ceiling is 100,000 recipients per campaign (422 campaign_too_many_recipients).
4. Check the preview
Section titled “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
Section titled “5. Schedule or start now”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_atbetween 1 minute and 90 days ahead (422campaign_schedule_invalid).- It needs at least one valid recipient (
campaign_no_recipients) and no import in progress (campaign_import_in_progress). POST /startlaunches now;POST /unschedulegoes back to draft.
Speed and the portfolio tier
Section titled “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 withrate_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
Section titled “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
Section titled “131049 and the 24 hours”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
Section titled “Monitoring and the report”GET /v1/campaigns/{id}/recipients?status=failedlists recipients by status:pending,invalid,sending,sent,delivered,read,failed,unknown,skipped.unknownis 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}/reportreturns a CSV withto,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.completedandcampaign.canceled. Messages carrycampaign: { id, recipient_id }inmessage.sentandmessage.status. See Events.