​

Run a WhatsApp marketing campaign end-to-end

​

1. Prerequisites

• A connected WABA with at least one approved marketing template. Business-initiated WhatsApp sends leave only as templates — there is no free-form blast equivalent. If you have not onboarded yet, start with the WABA setup guide; the 24-hour window guide explains why templates are the only permissible content outside an open customer-service window.
• An API key with the campaigns:write scope. Reads (audience preview, dry-run, stats) accept campaigns:read; launch requires write.
• An opted-in recipient audience. Opt-outs and suppression are enforced at send time; Meta additionally throttles marketing-template delivery for low-quality WABAs, so engagement-quality audiences matter more here than on SMS. Recipients outside the 24-hour window are reached by the template; recipients with an open window still count toward your per-recipient messaging-limit tier.

​

2. Pick and bind the approved template

​

3. Create the draft

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer sale — WhatsApp VIP drop",
    "type": "blast",
    "channel": "whatsapp",
    "audience_type": "list",
    "audience_id": "list_summerVIPs",
    "message_template": "summer_drop_vip_v2",
    "send_time_optimization": "fixed"
  }'

"channels": [
  {
    "channel": "whatsapp",
    "order": 0,
    "fallback_on": "failed",
    "fallback_after_seconds": 300,
    "whatsapp_template": { "name": "summer_drop_vip_v2", "language": "en" }
  },
  { "channel": "sms", "order": 1 }
]

​

4. Preview the audience

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/audience/preview" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "audience_type": "list", "audience_id": "list_summerVIPs", "channel": "whatsapp" }'

​

5. Dry-run: the WhatsApp gates

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/dry-run" \
  -H "X-API-Key: $ORBIT_API_KEY"

• Template pre-flight. Launch resolves message_template against your synced template registry and requires status: "approved". A missing template name means the local registry has never seen it — sync templates from Meta, then retry.
• Quality rating. If your WABA’s quality rating has dropped to red, the campaign auto-pauses with reason whatsapp_quality_red rather than burning quota on sends Meta will throttle anyway. Clear the quality issue in Channels → WhatsApp → Health, then resume the campaign.
• Messaging-limit tier. The dry-run projects cost against the same resolver the send path uses, but the audience size must also fit your current per-24h unique-recipient tier (250 on a new WABA, scaling to unlimited). Check your tier under Channels → WhatsApp → Health before launching at a large list; an over-tier audience fails recipients at send time, not at launch.

​

6. Launch

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/send" \
  -H "X-API-Key: $ORBIT_API_KEY"

​

7. Callbacks: what WhatsApp reports that SMS cannot

• Campaign lifecycle — campaign.started, campaign.completed, campaign.paused (including the whatsapp_quality_red auto-pause), campaign.drip_step.sent for drip shapes.
• Per-message outcomes — message.sent (accepted by the provider), message.delivered (device receipt), message.read (the recipient opened it — a signal SMS never produces), and message.failed carrying the Meta error code, e.g. (#132015) too many business messages when Meta throttles marketing deliveries.
• Replies — an inbound reply inside (or opening) the 24-hour window arrives as message.received. Route it into the inbox or your own automation; the normalized inbound envelope describes the payload shape, and the webhook consumer guide covers signature verification, retries, and dead letters.

​

8. Read rate discipline

​

Troubleshooting

• Launch 422: template not found locally. The template registry has not synced the name — pull templates from Meta (Channels → WhatsApp → Templates → Sync) and retry. Re-check spelling; template names are case-sensitive.
• Launch 422: template status is not approved. Resubmit or pick an approved template. Only APPROVED templates can send; PAUSED and DISABLED count as blocked.
• Campaign auto-paused with whatsapp_quality_red. The WABA quality rating dropped to red. Resolve the quality issue, then POST /api/v1/campaigns/:id/resume.
• High message.failed with Meta code (#132015). Meta is capping how many marketing-template messages one recipient receives in a window. This is recipient-side filtering, not an Orbit failure — narrow the audience or change the message category.
• Audience preview resolves to zero. Re-run the preview with channel: "whatsapp" — the net projection names the emptying cohort (all opted out, no reachable WhatsApp number).