Skip to main content

​
Inbound message resolution

Inbound message resolution answers one question for every mobile-originated (MO) SMS or carrier delivery receipt (DLR) that reaches Orbit: which tenant does this belong to? Resolution runs before any routing rules or inbox assignment — a message that cannot be resolved to a tenant is dropped before anything else sees it. This page explains that ownership step end to end. Tenant-level routing rules that further distribute a resolved message (keyword or sender match into a webhook, queue, inbox, team, or SMS menu) are covered in Inbound message routing. Everything below is the tenant-ownership layer underneath that rule engine.

​
How inbound resolution works

Every inbound MO or DLR carries a destination phone number (your DID) and a sender. Orbit resolves the destination number to its owning tenant in four ordered steps, stopping at the first hit:
  1. Platform inventory. The destination number is looked up in the platform number index — the inventory of numbers purchased through Orbit that are stamped to a specific organization. Owners of deleted organizations never match; the lookup only resolves to a live organization.
  2. Trial-pool assignments. Shared trial numbers handed out for time-bounded testing resolve through their active assignment window.
  3. The reverse-ownership map. A dedicated number index maps a phone number directly to its owner, updated when a number is purchased and removed when it is released. This is the O(1) path that covers direct-carrier purchases and keeps resolution fast at any cluster size.
  4. Bounded fallback scan. When none of the index paths hit, resolution scans tenant records to find an owner, checking each tenant’s own numbers. The scan is deliberately bounded: it refuses to guess when two tenants both claim the number (ambiguous ownership drops the message instead of risking a cross-tenant leak), and when no owner is found the message is discarded as unroutable. It only fires for numbers missing from the index — not for genuinely unowned numbers, which are correctly dropped.
Resolution is a guard, not just a directory lookup: a resolved route whose recorded owner disagrees with current ownership is rejected, and the message falls back to the tenant-wide default. This is what stops a recycled DID — released by one tenant and re-claimed by another — from delivering the new owner’s inbound content to the previous owner’s webhook endpoint.

​
The routed number states

A number only resolves inbound traffic while it is owned in one of three states: active, pending_compliance, or suspended. Numbers in any other state — released, parked, or never purchased — do not own inbound traffic, and messages addressed to them are discarded at the resolution step.
  • active — fully usable; inbound lands normally.
  • pending_compliance — purchased into a regulated country while the compliance bundle verifies. Still owned, so inbound resolution still lands it; the number is never orphaned during verification.
  • suspended — a soft pause (for example an overdue balance). Suspend stops usage, but ownership is retained so inbound resolution continues to route; inbound does not fall into an unowned-number black hole.
Release the number and the reverse-ownership entry is removed, so resolution correctly stops resolving. See Number status map for the full state vocabulary and Number lifecycle for the transitions between them.

​
The hourly self-healing reconcile

Index completeness is not dependent on every purchase-time write succeeding. An hourly background reconciliation scans every live tenant’s SMS-capable numbers and re-creates any reverse-ownership entries that drifted — for example when a purchase-time write failed silently, or an out-of-band administrative edit bypassed the normal write path. A one-time drift therefore self-clears within one hour; inbound that spontaneously returns after the next hourly window is the expected self-heal path, and no support action is needed. There is also a per-message self-healing path: when the bounded fallback scan unambiguously resolves an owner, the reverse-ownership index is backfilled on the spot, so the next inbound message for that number resolves through the O(1) index lookup instead of re-running the scan. Resolution paths layer this way intentionally: fast indexed lookups handle the common case, the bounded scan catches drift, and the hourly sweep repairs the index so the scan stays rare.

​
The per-DID route override

Resolution decides which tenant receives the message. The per-DID route override decides where inside the tenant the message terminates. Each DID carries an optional route override — the dashboard route configuration panel on the number — with an sms_route_type of webhook, agent, auto_reply, or disabled:
  • webhook — the inbound content is POSTed to your HTTPS endpoint (with an optional secondary delivery target). Use this when your own service consumes inbound.
  • agent — the message is handed to an AI agent for two-way conversation over SMS. Use this when replies should come from an agent rather than a human.
  • auto_reply — one fixed response body (up to 1600 characters) is sent back for each inbound message. Use this for acknowledgment-only numbers.
  • disabled — nothing. The message is resolved into your tenant’s inbox but never dispatched anywhere. Voice-style routing for the same DID is unaffected; the toggle is SMS-specific.
Why you must set it deliberately: disabled makes inbound look exactly like a resolution failure — the message arrives, resolves, is stored, and then goes nowhere. When a number receives texts but your integration hears nothing, check the override before suspecting resolution. The inbound troubleshooting flow lists clearing a disabled override as the first escalation gate for exactly this reason.

​
Subaccounts share resolution

Sibling subaccounts share the parent’s tenant schema, so a number bound to one subaccount resolves inbound for the whole organization — the inbound becomes visible at the organization level, not only to the owning subaccount. Cross-tenant boundaries are unaffected: a sibling subaccount can receive your inbound, an unrelated tenant never can. What siblings do and do not share is detailed in Tenant isolation.

​
Subscription gaps never break resolution

Inbound routing correctness is not gated on billing status. A tenant whose subscription has cancelled keeps its provisioned schema and its SMS-capable numbers, and the hourly reconciliation continues to enumerate and repair it — resolution never checks subscription state. A cancelled-subscription tenant’s inbound keeps routing and keeps self-healing; what subscription controls is spend and usage, not the ownership index.

​
See also