​

Run an RCS marketing campaign end-to-end

​

1. Prerequisites

• An agent (bot) launched on at least one carrier. An RCS campaign sends only through a carrier-launched agent — a draft, pending_verification, or pending_launch bot fails the pre-flight. If you have not onboarded yet, start with the RCS onboarding guide; the brand → agent → verify → launch sequence takes days, so do it before any campaign planning.
• An approved template registered to that agent. Campaign sends reference templates by name, and only Approved templates pass the launch gate. Author and submit it in the Rich Card Studio, and read its approval badge on the Templates tab. A template pending carrier review blocks the launch.
• An audience sized by reach scan. RCS reachability is per device — a list that looks large can be half non-capable. Run the reach scan in step 2 before you commit the segment to a rich-media send.
• An API key with the campaigns:write scope. Reads (reach scan, 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; the SMS fallback hop passes through the same opt-out screening as a pure SMS campaign.

​

2. Pick reach: scan before you build

curl -X POST "https://api.orbit.devotel.io/api/v1/rcs/reach-scan" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "bot_4kqzx1",
    "segment_id": "seg_summerVIPs",
    "sample_size": 100
  }'

{
  "data": {
    "segment_id": "seg_summerVIPs",
    "bot_id": "bot_4kqzx1",
    "sampled": 100,
    "capable": 63,
    "reach_percent": 63,
    "recommended_channel": "mixed"
  }
}

• rcs — most of the segment is capable; a single-channel RCS campaign is viable, but a short SMS ladder still protects the minority.
• mixed — some recipients are capable, some are not; use the RCS-first ladder with SMS as the terminal hop (step 3). Never ship a mixed verdict as RCS-only — every non-capable recipient hard-fails.
• sms — the segment is mostly non-capable; either keep this send on SMS, or ship the ladder anyway knowing most recipients settle on the SMS hop.

​

3. Build the campaign: template attached, agent bound

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 — RCS VIP drop",
    "type": "blast",
    "channel": "rcs",
    "audience_type": "list",
    "audience_id": "list_summerVIPs",
    "message_template": "summer_drop_card_v2",
    "send_time_optimization": "fixed"
  }'

"channel": "rcs",
"channels": [
  {
    "channel": "rcs",
    "order": 0,
    "fallback_on": "failed",
    "fallback_after_seconds": 120,
    "rcs_template": { "name": "summer_drop_card_v2" }
  },
  { "channel": "sms", "order": 1 }
],
"name": "Summer sale — RCS-first with SMS fallback",
"type": "blast",
"audience_type": "list",
"audience_id": "list_summerVIPs",
"message_template": "Summer sale VIP drop — link below. Reply STOP to opt out."

​

4. Pre-flight: dry-run plus audience preview

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": "rcs" }'

• No capability. Contacts whose devices were probed and reported non-capable (or whose handset carrier is not among the agent’s launched carriers) drop out of an RCS-only preview. If the unreachable share is large, add the SMS ladder from step 3 or restrict the audience to capability-verified recipients.
• Template pending. On a ladder, the RCS hop is treated as unconnected when its template is not Approved, and recipients who would only reach the rich message fall to the SMS hop. On an RCS-only campaign, a pending template blocks the launch outright.

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

• Agent readiness. The bot must be launched on at least one carrier — the pre-flight reads GET /api/v1/rcs/bots/:id/quality for the carrier_statuses map. A campaign pointing at a draft or pending-launch bot reads unconnected and suppresses ready_to_launch.
• Template approval. Launch re-resolves message_template or the hop’s rcs_template against the agent’s roster; anything not Approved means back to the Templates tab.
• Fallback hop readiness. On a ladder, the SMS hop requires a dedicated sending number — the pre-flight probes every step, so an unprovisioned SMS sender also suppresses ready_to_launch. Details: pre-launch readiness for fallback chains.

​

5. Launch and read

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

• Campaign lifecycle — campaign.started, campaign.completed, campaign.paused.
• Per-message outcomes — message.sent (accepted by the carrier hub), message.delivered (device receipt), message.read (the recipient opened it — RCS reports a read receipt SMS never produces), and message.failed carrying the provider error, e.g. capability skip (RCS_NOT_SUPPORTED) or a carrier rejection on template content.
• Replies — inbound replies arrive as message.received; route them into the inbox or your own automation via the normalized inbound envelope.

​

6. Per-template analytics

curl "https://api.orbit.devotel.io/api/v1/rcs/analytics/templates?days=30" \
  -H "X-API-Key: $ORBIT_API_KEY"

​

7. Operate after launch

• Template edits mid-flight. Every PUT to a template resets approval to pending — a live campaign referencing it falls back to SMS (on a ladder) or starts failing (RCS-only). Freeze templates before launch; land edits between launches. The warning lives on the Templates tab too — sequence edits around launch windows.
• Rollback to SMS-first. If RCS delivery dips against a launch’s baseline, pause the campaign (POST /api/v1/campaigns/:id/pause), edit the ladder so channel: "sms" leads, and re-launch; or flip the org-level cross-channel fallback off for blast traffic until the carrier hub recovers. Either way the SMS hop keeps the audience reachable.
• Re-approve before renewal. Template approval does not roll into new definitions: when you revise copy for a seasonal reuse, resubmit and wait for Approved before scheduling the next send. The approval-state table on the Templates tab is the checklist.

​

Troubleshooting

• Launch 422: template not approved or not found. Re-sync the Templates tab and confirm the name — template names are case-sensitive. Only Approved templates send.
• Pre-flight: RCS hop unconnected. The bot is not launched on any carrier, or the ladder’s RCS template is pending. Poll GET /api/v1/rcs/bots/:id/quality for the per-carrier carrier_statuses.
• High message.failed with RCS_NOT_SUPPORTED. The recipients were never RCS-capable to this agent — shorten your capability cache or restrict the audience to probed-capable recipients; on a ladder, those recipients advance to SMS.
• Delivered stays high, read trends toward zero. Rich cards earn taps only if the card itself prompts one — compare the template’s rates against the rest of the roster on the Templates tab or the per-template analytics endpoint and iterate on the card content before scaling further.
• Sends skip recipients on some carriers. The agent is launched only on a subset of carriers — the org-level RCS → SMS fallback or your campaign ladder’s SMS hop covers the rest; compare carrier_statuses against where your audience sits before scaling traffic.