​

Fallback chains: pick and configure channel cascades across messaging and OTP

1. Campaign-level chains — the channels[] array on a campaign (failed / no_delivery / no_engagement triggers + a fallback_after_seconds window per non-final entry). Best for marketing blasts, drips, and journeys. Covered in the campaign end-to-end guide under “Channel fallback ladder”.
2. Per-message cascade policy — a cascade_policy object on POST /messages/smart-send (or read-only on POST /messages/route-preview) that resolves an explicit or router-suggested fallback set and stamps it onto the message metadata as fallback_channels. Best for transactional traffic. Full detail in the smart-send fallback chains guide:

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/smart-send" \
  -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": "transactional",
    "rcs_available": true,
    "whatsapp_available": true,
    "cascade_policy": {
      "fallback_channels": ["whatsapp", "sms"],
      "segment": { "campaign_id": "cmp_retail_q3" }
    }
  }'

{
  "data": {
    "id": "msg_01H...",
    "channel": "rcs",
    "status": "sent",
    "cascade": {
      "primary": "rcs",
      "fallback_channels": ["whatsapp", "sms"],
      "ordering": "static"
    }
  }
}

3. Verify profile step-up chains — the ordered channels array on a Verify profile (sms → whatsapp → voice, and so on) that a background engine advances when the previous channel cannot deliver the code. Best for OTP and MFA.

​

1. Choose the chain type per use case

​

2. Channel-ordering rules (all three surfaces)

• First entry = the primary channel. For campaigns the top-level channel must equal channels[0].channel. For Verify profiles the send body’s channel should equal channels[0] (a different one is tacked on front, not an error). For cascade_policy the smart router picks the primary and the policy shapes only the fallback set — never the primary.
• The terminal entry carries no fallback fields. In a campaign chain, the last object in channels[] must not carry fallback_on / fallback_after_seconds — it is the hop that finishes the chain. The platform enforces this at validation; a chain whose last entry still declares a fallback trigger is rejected with a 422 naming the entry.
• Channel-specific fields live only on that channel’s entry. whatsapp_template is legal only on a channel: "whatsapp" entry — never on the sms or primary entry of a mixed chain. (Same rule holds for rcs_template, subject on email entries, etc. — see the campaign guide’s field table.)
• Duplicate channels are rejected. Depth and no-duplicate rules are enforced at create/update time (campaigns) and profile save time (Verify).
• Messaging-only entries in per-message cascades: voice and fax are filtered out of cascade_policy.fallback_channels; Verify chains additionally admit voice (with a templates.voice script containing {{code}} — mandatory) plus email, viber, telegram, rcs, flashcall.

​

3. Worked example A — WhatsApp-first → SMS (campaign chain)

{
  "channel": "whatsapp",
  "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 }
  ],
  "name": "Retail promo — summer drop",
  "type": "blast",
  "audience_type": "list",
  "audience_id": "list_summerVIPs",
  "message_template": "Hi {{first_name}}, early access starts now: 25% off through Sunday. Reply STOP to opt out."
}

​

4. Worked example B — OTP step-up (Verify profile)

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/profiles" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Login OTP",
    "channels": ["sms", "whatsapp", "voice"],
    "codeLength": 6,
    "expirySeconds": 600,
    "maxAttempts": 3,
    "rateLimitPerHour": 5,
    "templates": {
      "voice": "Your {{app_name}} security code is {{code}}. I repeat, {{code}}."
    }
  }'

​

5. Failure semantics: what counts as no_delivery vs no_engagement, and when the chain stops

• failed (campaign chains): a terminal DLR on the current hop — the carrier replied with failed, undelivered, or rejected. Cheapest trigger: the chain moves only when a hard failure is known.
• no_delivery (campaign chains, and the Verify advance engine’s timeout branch): no terminal DLR arrived within fallback_after_seconds (campaign) or channel_timeout_seconds (Verify). Use it for channels whose carriers routinely leave you hanging, or for WeChat where template sends may never produce a delivery callback.
• no_engagement (campaign chains only): the message was delivered but produced no open/read/reply event within the window. This hop costs a second send and should be used sparingly — measure the engagement criteria carefully before enabling it.
• Verify profiles advance on either a delivery failure or the timeout (above). no_engagement does not apply to OTP: a delivered code that is not yet approved is not a deliverable-channel failure.
• The chain stops when a hop succeeds, when the terminal hop is reached, or (Verify) when every hop has failed (verification.fallback_exhausted fires). Every hop’s outcome is attributed on its DLR webhook under its own message id (per-message cascades / campaign chains) or the verification.fallback_triggered event (Verify), so a per-hop attribution read always shows the final outcome per hop, not one aggregated status.
• A per-message fallback never re-arms an expired message: fallback_window_seconds (default 24 h) caps how fresh the original send must be for a terminal DLR to escalate (see Fallback on terminal DLR).

​

6. Cost: per-hop billing, and cap the whole thing

• max_price (per-binding or request-level): reject a single hop whose projected price exceeds the cap before billing it — a pricey RCS hop can be skipped without burning the SMS tail.
• max_total_price: a cumulative budget across the whole waterfall — the chain is trimmed at arm time so the running total of kept hops never exceeds your declared cap.

​

7. Preview a chain before arming it

• POST /messages/route-preview — resolves the smart router’s primary pick and your cascade_policy (explicit or router-suggested) and returns the resolved chain under a cascade block with the ordering (static / adaptive / off). Total cost estimate included. See the smart route preview guide.
• POST /campaigns/:id/preview-smart-send — on a send_time_optimization: "recipient-optimal" campaign, returns per-recipient recommended times plus a next_best_channel hint so you can see what channel each recipient would land on before the bulk send commits. See the campaign end-to-end guide step 6.

​

8. Where each surface links next

• Campaign chains: Send a campaign end-to-end (step 6 “Channel fallback ladder”) and the WhatsApp campaign launch playbook.
• Per-message cascades: Smart-send fallback chains and Smart route preview.
• Verify profiles: Verify fallback chains and advanced factors.
• Underlying concepts: Cross-channel fallback, Fallback on terminal DLR, Notify cascade cost model, Cascade groups and planes.