​

Upgrade SMS traffic to RCS per recipient

​

1. Upgrade vs fallback: pick the mechanism

​

2. Detect per-recipient RCS capability

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/route-preview" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "body": "Your order #8421 shipped — track it here.",
    "message_type": "marketing",
    "urgency": "low",
    "rcs_available": true,
    "country": "US"
  }'

{
  "data": {
    "channel": "rcs",
    "reason": "Rich content for marketing",
    "fallback": "sms",
    "fallbackChain": ["sms"],
    "estimatedCostCents": 2,
    "engagementScore": 0.74
  }
}

​

3. Author the RCS-first campaign ladder

{
  "channel": "rcs",
  "channels": [
    {
      "channel": "rcs",
      "order": 0,
      "fallback_on": "failed",
      "fallback_after_seconds": 120,
      "rcs_template": { "name": "order_shipped_card_v3" }
    },
    { "channel": "sms", "order": 1 }
  ],
  "name": "Order shipped — RCS upgrade pilot",
  "type": "blast",
  "audience_type": "list",
  "audience_id": "list_recentBuyers",
  "message_template": "Your order #8421 shipped — track it here. Reply STOP to opt out."
}

• The RCS hop fires first. It can carry either a raw rich payload (rich_card / rich_card_carousel shape from the RCS channel page) or an rcs_template reference to an approved template from the Templates tab — never both, and rcs_template is legal only on the rcs entry.
• The SMS hop is terminal. It carries no fallback_on / fallback_after_seconds; the platform rejects a chain whose last entry still declares a trigger. SMS sends from your normal sending number with normal opt-out screening.
• The advance trigger decides who stays on RCS. fallback_on: "failed" moves a recipient to SMS only on a terminal RCS failure (undelivered / rejected, including the capability check returning RCS_NOT_SUPPORTED). fallback_on: "no_engagement" would also move delivered-but-ignored recipients to SMS — a second paid send per recipient — so keep the trigger on failed for an upgrade and measure engagement on the RCS hop instead.

​

4. Validate in sandbox

​

5. Read per-hop DLRs

{
  "notify_id": "notify_2kR8wQv1mN",
  "status": "delivered",
  "hop_count": 2,
  "hops": [
    {
      "hop": 0,
      "channel": "rcs",
      "status": "failed",
      "error_code": "RCS_NOT_SUPPORTED",
      "price": 0.0000,
      "currency": "USD"
    },
    {
      "hop": 1,
      "channel": "sms",
      "status": "delivered",
      "error_code": null,
      "price": 0.0084,
      "currency": "USD"
    }
  ],
  "delivered_channel": "sms",
  "cost": { "total": 0.0084, "currency": "USD" }
}

• error_code mix on the RCS hop. RCS_NOT_SUPPORTED means the recipient was never RCS-capable — a signal to fix your capability flagging (step 2), not the ladder. Carrier rejections mean template or sender issues instead.
• delivered_channel distribution. The share of recipients settling on SMS is your true RCS reach in the wild; compare it against the reach scan’s estimate.
• cost.total vs the SMS-only baseline. A failed RCS hop that short-circuits on capability is free; an RCS hop that attempts and fails still bills. If the terminal-SMS share is high and RCS attempts are costly, restrict the audience to capability-verified recipients.

​

6. Rollout gates

1. Pre-flight the chain. POST /api/v1/campaigns/{id}/preview now probes every fallback step, not just the primary — for this ladder it verifies the RCS hop has a verified brand agent and the SMS hop has a dedicated sending number. A step that reads unconnected suppresses the green ready_to_launch. Details: Pre-launch readiness for fallback chains.
2. Pilot a slice. Launch the ladder against a small segment (or a versioned audience slice) and read the per-hop receipts from step 5.
3. Widen or narrow by what the receipts say. A high RCS_NOT_SUPPORTED share means your capability flags are stale — shorten the cache window before widening. A healthy RCS-delivered share means widen to the full audience.
4. Keep SMS in the ladder forever. Every advance trigger keeps an exit to SMS; removing it strands non-capable recipients with a hard failure.

​

7. Limits and exclusions

• Approved brand + agent first. An RCS hop in any ladder fires only for a verified or launched agent; the campaign pre-flight flags a draft agent as unconnected. There is no sandbox bypass around the approval.
• Voice never joins the ladder. voice and fax are filtered out of cascade chains — OTP step-up via a Verify profile is the only surface that admits voice, and that is a different plane.
• Org-level fallback is the wide net. The RCS channel page also offers an org-wide RCS → SMS chain under Settings → Channels → Cross-Channel Fallback that applies to every RCS send without a campaign ladder. A campaign ladder overrides it for that campaign; leave the org chain armed as the backstop for direct API sends.
• Templates gate separately. An rcs_template hop sends only after that template is approved — a PUT to the template resets approval to pending, so publish template edits before the campaign depends on them.

​

Where to go next

• RCS channel page — capability check, org-level fallback, reach scan, templates.
• Fallback chains — the full plane map across campaigns, smart-send, and Verify.
• RCS onboarding — brand → agent → verify → launch.
• Track a live cascade by notify id — the per-hop receipt surface.