Inbound voice routing

Inbound voice routing answers two questions for every call that lands on one of your numbers: which organization does this dialed number belong to, and where inside that organization should the call terminate — a queue, a SIP device, an IVR flow, an AI agent, a voicemail box, a conference room, or your own webhook endpoint. Resolution runs at call setup, before any media flows, and always produces something playable: a caller never lands on dead air because no route was configured. This page covers the voice path end to end. The messaging analogue — how an inbound SMS resolves from number to tenant — lives in Inbound message resolution, and the tenant-level SMS rule engine lives in Inbound message routing. The state transitions a call goes through after routing (ringing, answered, completed) are covered by Voice call lifecycle; this page stops at the moment the routing decision is made.

Why the routing tables are shared, not per-tenant

Per-tenant data in Orbit lives in one schema per tenant — messages, contacts, recordings, and flows never touch a tenant boundary. Inbound routing is the deliberate exception. Two routing tables live in the shared platform catalog, and both carry an organization id on every row:

Shared table	Role
`dnis_routes`	Pattern rules that match a dialed number by E.164 prefix or regex and resolve to a route target
`inbound_routes`	Per-number route: one row per owned DID carrying the voice termination (type + config), an optional fallback, and an optional per-number SMS handler

They sit in the shared catalog because the answers they hold are inherently platform-wide: “which organization owns this number” and “where do calls to this number terminate” must be resolvable at the SIP edge, before any tenant context exists, using the number itself as the only input. A dialed number is a global identifier, so its routing record is a global lookup. The tenant boundary is still enforced, just differently: instead of schema separation, every row carries an organization id, and the resolver re-validates each row’s organization against the authoritative number-ownership record before honoring it (the stale-route guard described below). Both tables are listed in the shared-catalog section of Tenant isolation.

The resolution chain

An inbound call arrives at the SIP edge as a SIP INVITE addressed to your DID. The edge asks the voice API for a routing decision, which resolves in four ordered steps and stops at the first hit:

Per-number route. The dialed number is looked up in the per-number route table. One number terminates exactly one way — an exact match always wins over any pattern rule.
DNIS pattern rules. With no per-number row, the resolver loads the owning organization’s pattern rules (E.164 prefix or regex). Surviving matches are ordered by ascending priority, then longest pattern, then oldest rule — one row can steer a whole country pool of toll-free numbers, while a per-number route on a VIP line still beats the pattern.
Org default. The number is owned but has no route: the org-level default plays (an optional consent announcement, then the standard “this line isn’t available” voicemail-style handling), so an unconfigured number still answers politely.
Safe default. The number has no route and no owning organization — or the resolution database is briefly unreachable — and the safe-default “line not available” sequence plays. This is the fail-open floor: a transient database error degrades the call to a polite announcement, never to a dropped INVITE.

Ownership and routing are checked independently on every call and validated against each other. The per-number route row and the authoritative number-ownership record are read separately, and the route is honored only when its organization agrees with the current owner. A released-then-rebought number can leave a stale route row behind from the prior owner; when the organizations disagree, the route is rejected on the spot and the call re-resolves through steps 2–4. That guard is what prevents a recycled DID from streaming calls, recordings, and voicemails into the previous owner’s tenant. Suspended or deleted organizations are rejected at the same gate.

Where the resolution output feeds

The resolution chain produces one route — a target type plus target-specific config — and the destination machinery consumes it. What those destinations are:

Target	Where the call lands
`queue`	An ACD queue: the caller holds with music while skill-based routing picks an available agent, with business hours, holiday calendars, and overflow applied
`ring_group`	A reusable, nestable ring group — resolved to a parallel or sequential fan-out across its member devices and numbers
`softphone_user`	A specific user’s browser softphone
`softphone_register`	Registered SIP devices by username — desk phones and apps ring simultaneously or sequentially; the hot-desking shape, where one physical phone serves whoever registers on it
`agent`	An AI voice agent in a video room
`ivr`	A flow or AI-agent IVR
`voicemail` / `dispatch_to_voicemail_box`	A personal voicemail or a shared department mailbox
`sip_forward`	Your external SIP server (BYO PBX)
`transfer`	A fixed PSTN destination
`conference`	A named conference room, optionally PIN-gated
`webhook`	Your own HTTPS endpoint, which returns the call-handling instructions for that call (HMAC-signed, HTTPS-only, with a secondary URL for DR)
`decline`	An immediate SIP 603 — for deprecated or honeypot numbers

The queue target is the bridge into the contact-center side of the platform. Behind the queue sits the same presence and capacity engine that distributes every work item: the router reads the queue’s agent membership, the per-queue presence machine (available, busy, wrap-up, paused, offline), skill proficiencies, and each agent’s blended voice-and-digital load, then hands the item to the best eligible agent. Voice is one work-item class through that engine — email and ticket items route through the same queues and the same presence gates — which is why an agent answering calls is never also handed a ticket mid-call, and a queue you staff once serves both channels. Ring groups and registered devices are picked up by the same fleet of SIP credentials: hot-desking (a sharable physical phone that belongs to whoever is registered on it) is just a registered-contact ring strategy, not a separate routing feature. Most destinations honor their route’s fallback column: when the primary path fails to terminate (agent offline, softphone unregistered, queue empty past its wait window, webhook endpoint down), the fallback — commonly voicemail — fires instead. Operators with a misconfigured primary still end at a mailbox rather than silence.

Failure edges

Every gap in the chain has a defined outcome:

Unassigned number. No route row, and the number has no owning organization (not purchased, or released). The safe-default announcement plays; no organization hears about the call.
Organization not ready. A number can resolve to an organization whose tenant schema is still provisioning. Inbound routing only needs the shared catalog, so calls to a mid-provisioning number take the safe-default path — the same window where account-scoped APIs return 503. The 503 semantics and the readiness flag are covered by Provisioning and test mode.
Suspended owner. The resolved organization is soft-deleted, cancelled, or suspended. The call is rejected rather than routed into a frozen tenant.
No matching rule. With no per-number row and no matching pattern, the org default handles the call: a mailbox, not silence.
Resolution database unavailable. Every ownership and routing read fails open to the safe default, because a polite “line not available” beats a database blip dropping live calls.
STIR/SHAKEN policy. An organization can set a minimum inbound attestation level per route or per DNIS rule; callers below it are declined at setup with a SIP 603.
Caller screening. Per-route caller-id allow, block, and VIP filters are applied after routing, so a filtered caller gets a defined denial rather than the route’s destination.

Inbound routing never originates outbound traffic. Targets either terminate locally (queues, devices, voicemail) or splice through the platform’s own voice path; forwarding destinations are inbound-only legs by construction.

Sample trace

Call from +15553001000 to your support DID +18005550100:

Per-number lookup → no row.
The number resolves to your organization; DNIS rules load. Your +1800 prefix rule points those numbers at the support queue.
Caller screening → STIR/SHAKEN attestation parsed, meets your per-rule minimum.
Business hours → open, inside your 09:00–17:00 window.
Queue → destination queue_support; the router picks an available, in-skill agent with the lowest blended load; the agent’s softphone rings.
Fallback armed → if the queue sits unanswered past its wait limit, voicemail fires.

The routing decision as data:

{
  "dialed": "+18005550100",
  "from": "+15553001000",
  "resolvedVia": "dnis_rule",
  "organization": "org_acme",
  "rule": {
    "name": "Toll-free pool → Support",
    "pattern": "+1800",
    "priority": 100
  },
  "destination": {
    "type": "queue",
    "queueId": "queue_support",
    "maxWaitSec": 90
  },
  "screening": {
    "attestation": "B",
    "callerIdFilter": "allow"
  },
  "fallback": { "type": "voicemail" }
}

The shape above mirrors what the queue-destination route’s config carries (queue id plus optional wait limit and hold-music override) — inspectable per number on the dashboard and in per-call records via the resolved routing attribution.

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

Inbound voice routing

Inbound voice routing

Why the routing tables are shared, not per-tenant

The resolution chain

Where the resolution output feeds

Failure edges

Sample trace

See also

​Inbound voice routing

​Why the routing tables are shared, not per-tenant

​The resolution chain

​Where the resolution output feeds

​Failure edges

​Sample trace

​See also

Inbound voice routing

Why the routing tables are shared, not per-tenant

The resolution chain

Where the resolution output feeds

Failure edges

Sample trace

See also