​

Smart routing: preview a channel before you send

​

When to preview vs. send

• Planning a campaign. Before you commit an audience to a channel, run the preview against a sample of recipients. If the recommendation is not the channel you assumed, adjust the audience or the capability flags — not the campaign after launch.
• Validating channel-cost before pacing. estimatedCostCents is priced through the same channel cost table the router scores with, so a preview loop over a recipient cohort gives you a per-channel cost picture for pacing decisions (throttle, credit caps) before the first dispatch.
• Fallback sanity checks. Toggle the capability flags (whatsapp_available, rcs_available, …) to confirm the router degrades the way you expect — e.g. that an RCS-first marketing blast lands on WhatsApp or SMS rather than voice when RCS is off.
• Picking a send shape. If channel: "auto" outperforms your fixed channel on engagement for a cohort, switch the campaign to auto-routing before you schedule it.

​

Endpoint shape

​

Request

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": "transactional",
    "urgency": "medium",
    "whatsapp_available": true,
    "rcs_available": true,
    "email": "sara@example.com",
    "country": "US",
    "cost_optimize": true,
    "engagement_rates": { "whatsapp": 0.91, "sms": 0.38 }
  }'

​

Response — 200

{
  "data": {
    "channel": "whatsapp",
    "reason": "Best channel: high engagement (91%)",
    "fallback": "rcs",
    "fallbackChain": ["rcs", "sms", "email"],
    "estimatedCostCents": 3,
    "engagementScore": 0.91
  }
}

​

Read the response, field by field

• channel — the router’s pick. One of sms, whatsapp, email, viber, rcs, push, voice. This is the channel a dispatch with the same inputs would use.
• reason — a plain-text explanation of why it won, composed from whichever factors fired: cost-optimized (cost-optimize is on and the pick is cheap), high engagement (N%) (the pick’s engagement meets the 70% threshold), fast delivery for urgent message, rich content for marketing. When nothing distinctive fired, the reason states the pick scored highest for that recipient and message type. Two special cases: OTP messages return the regulatory SMS rule verbatim, and a recipient with no detected capabilities returns "No channel capabilities detected — defaulting to SMS".
• fallback and fallbackChain — fallback is the next channel to try; fallbackChain is the full ordered list after the recommended channel, in priority order. The first entry always equals fallback. Wire the chain into your send logic so a hard failure on the primary hops to fallbackChain[0], then [1], and so on. An empty array means no other channel is reachable for that recipient — treat the primary pick as terminal.
• estimatedCostCents — per-message cost in cents on the recommended channel, before any volume tiering. Sub-cent channels (email, push at 0.1¢) come back as fractional values, so multiply rather than round when you sum a cohort. Multiply by your cohort size for a planning total.
• engagementScore — predicted engagement probability, 0.0–1.0. This is your engagement_rates value for the recommended channel when supplied, otherwise the platform default for that channel. Use it to compare channel strategies across a cohort — a marketing blast where auto-routing averages 0.7 and your fixed channel averages 0.45 is a signal to switch.

​

Wire the preview into a send pipeline

prefetch (capabilities, engagement history)
      -> POST /messages/route-preview  (read-only, cheap)
      -> dispatch on recommendation.channel
      -> on hard failure: advance through fallbackChain
      -> last resort: defer to org-level cross-channel fallback config

import { Orbit } from '@devotel/sdk-node'

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY })

async function sendWithPreview(recipient) {
  // 1. Look up what this recipient can actually receive on.
  const capabilities = await getCapabilities(recipient.id) // your store

  // 2. Preview — read-only, safe to call per recipient.
  const preview = await orbit.request('POST', '/api/v1/messages/route-preview', {
    data: {
      to: recipient.phone,
      body: recipient.messageBody,
      message_type: recipient.messageType,   // 'transactional' | 'marketing' | 'otp'
      urgency: recipient.urgency,            // 'low' | 'medium' | 'high'
      whatsapp_available: capabilities.whatsapp,
      rcs_available: capabilities.rcs,
      viber_available: capabilities.viber,
      push_available: capabilities.push,
      email: capabilities.email ?? undefined,
      country: recipient.country,            // 'US'
      cost_optimize: true,
      engagement_rates: recipient.engagement, // { sms: 0.4, whatsapp: 0.8, ... }
    },
  })
  const recommendation = preview.data

  // 3. Dispatch on the recommended channel via the unified send.
  //    An explicit channel pins the pick; the same payload also works
  //    with channel: "auto", which re-runs the identical scoring at send time.
  const chain = [recommendation.channel, ...recommendation.fallbackChain]
  for (const channel of chain) {
    try {
      return await orbit.request('POST', '/api/v1/messages', {
        data: { to: recipient.phone, body: recipient.messageBody, channel },
      })
    } catch (err) {
      // On a hard, non-retryable failure, advance to the next hop.
      if (!isHardFailure(err)) throw err
    }
  }
  throw new Error('Exhausted fallback chain')
}

• Trust the chain, not your own ladder. The returned fallbackChain already encodes capability and cost ordering. Hand-rolled ladders skip that math.
• Org-level fallback still applies. If your tenant has cross-channel fallback rules configured (Settings → Channels → Cross-Channel Fallback), transparent retry on terminal delivery failures continues below your chain — see Messaging Best Practices.

​

Preview interactively: Outbound → Route Preview

​

route-preview vs. the composite risk verdict

​

Failure modes and safety properties

• Read-scoped keys work. A messages:read key can call the endpoint; you do not need to hand a planning job a write key.
• Nothing ever sends. The endpoint runs the scoring function and returns — it writes no message row, touches no wallet, and emits no webhook. Repeatedly calling it in a planning loop is safe and cheap.
• No cross-tenant leakage. Responses are computed from the request body plus platform defaults. When you omit engagement_rates, the defaults are global per-channel constants — the preview never reads another tenant’s data, and it returns your own historical rates only when you supply them.
• 422 VALIDATION_ERROR. A malformed body (missing to, body, message_type, or urgency; bad enum value; engagement rate outside 0–1) fails schema validation before any routing runs. Validation errors are reported once per field with a human-readable message — fix the named field and retry. The fix path does not need a retry loop.
• All-capabilities-off is not an error. A recipient with no flagged capabilities and no email gets a 200 with channel: "sms" and the diagnostic reason "No channel capabilities detected — defaulting to SMS". Decide in your pipeline whether that fallback suits the recipient — it is the router’s last-resort default, not a delivery guarantee.
• Rate limit. The route sits behind the tenant-keyed read budget (per-tenant, per-minute). A planning pass over a large cohort should still pace calls or batch over seconds — a 429 returns retry_after and is safe to retry after that window.