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.

DNIS pattern fallback: longest match wins

A DNIS rule is either an E.164 prefix (+1800 covers a toll-free pool, +44800 covers UK freephone) or a full regex over the dialed digits. When several rules match on one call, the resolver orders them deterministically:

Priority ascending — a lower priority value ranks higher.
Longest pattern — within the same priority, the more specific pattern beats a shorter, more general one. A +1800555 rule for a specific line takes the tie over a +1800 pool rule; the pool rule only sees numbers no specific line claims.
Oldest rule — fully tied rules resolve to the rule created first, so outcomes stay repeatable rather than load-dependent.

Ordering is a property of the rule set, not of the dialed number, so a caller hitting your toll-free pool always resolves the same way regardless of which number in the pool was dialed. The safety boundary that keeps pattern rules tenant-scoped: the resolver first asks which organization owns the dialed number, and only then evaluates that organization’s rules. Your +1800 rule can never catch another tenant’s toll-free DID, and another tenant’s rules are never considered for your number — even when a regex would match. This is the same scope the stale-route guard enforces for per-number rows: a released-then-rebought DID carries no surviving rules from the prior owner, because the candidate rule set comes from the current owner’s attested organization id.

Business hours and holiday calendars

Each route row may carry two schedule fields, one for ordinary opening hours and one for dated closures:

Business hours — a weekly schedule in your organization’s timezone, with one or more windows per weekday. Inside the window, the route’s primary destination applies; outside the window, the row falls through to the closed-hours fallback you configured — typically voicemail, an answering service, or your own webhook.
Holiday calendar — a dated closure list, evaluated before the weekly schedule. On a listed date the fallback applies all day regardless of what the weekly windows say.

Both fields default to open: a route with no schedule configured always uses the primary destination, and the fallback only exists when you set it. Holiday evaluation runs before the weekly table, so a holiday that falls on a business day still closes the line without you editing the schedule. A malformed schedule blob falls open too — a broken row means no restriction rather than dropped calls.

Verb plans: what the route executes

The softswitch thinks in verbs — the call instructions the voice edge executes in order for the life of the call — and the routing decision renders as one verb sequence. Your plan’s vocabulary:

Verb	What it does
`dial`	Bridge the carrier leg to a SIP device, a ring group, an external SIP forward target, or a PSTN transfer destination
`enqueue`	Park the call in an ACD queue where the presence engine’s next available agent picks it up
`say`	Play a spoken message (greeting, prompt, “the call cannot be completed”)
`gather`	Collect DTMF digits for PIN gates, menu sequences, voicemail access
`record`	Capture voicemail or an explicit recording leg
`hangup`	Terminate the call after the final verb

The sequence you configure — ring these devices, then the queue, then voicemail on no-answer — advances exactly once per no-answer step. A route with no fallback stops at the last configured verb; a route with a fallback chains into the fallback target’s own verb sequence when the primary reports a no-answer or failure status. Ring strategies (parallel versus sequential hunt across registered contacts) live inside the dial verb itself, not as adjacent verbs, so a softphone leg advances exactly once across the ring list. Every route row carries an optional caller-id filter that applies after routing and before the destination executes. You can:

Blocklist — a list of exact E.164 entries for repeat spammers or abusive callers. Matching calls hear a polite “the call cannot be completed” prompt and hang up; they never enter the queue, ring a device, or reach voicemail.
Reject anonymous callers — a per-route toggle that declines calls with a suppressed or withheld caller id, a recurring harassment vector. The toggle exists precisely because an anonymous caller carries no ANI to match against a blocklist entry.
VIP / allowlist (partial today) — the filter cell also stores a vip and allowlist set; those fields parse today while the dedicated allow-through path ships separately, so they are reserved for hardening rather than enforcement.

Normalization happens on the SIP From: header before comparison, so display-name headers, angle-bracket forms, IP-literal hosts, and explicit ports all resolve to the bare E.164 you stored. Prefix wildcards are deliberately unsupported: one entry like +1555 would brick an entire area code, so the filter only enforces exact, normalized matches. Malformed rows fail open (and log) so a broken filter cannot silence legitimate traffic.

Number status: the port-out pending window

When you initiate a port-out request for one of your DIDs, the number’s status flips to the synthetic port_out_pending marker — a platform-level stand-in for the regular active state while the losing-carrier mechanics play out. While port_out_pending is set, inbound routing continues to serve calls into the route row you already configured; the status exists to guard against destructive edits (releasing the number, re-routing to an unowned destination) during the transition window, not to mute the line. The full lifecycle of the marker — who sets it, why it returns to active, and what happens when the winning carrier completes — is covered by Number port-out, and the closed status enumeration it belongs to is in Number lifecycle.

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

Campaigns

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Tutorials

Changelog

Inbound voice routing

Inbound voice routing

Why the routing tables are shared, not per-tenant

DNIS pattern fallback: longest match wins

Business hours and holiday calendars

Verb plans: what the route executes

Caller-ID filter: block and allow at the route edge

Number status: the port-out pending window

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

​DNIS pattern fallback: longest match wins

​Business hours and holiday calendars

​Verb plans: what the route executes

​Caller-ID filter: block and allow at the route edge

​Number status: the port-out pending window

​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

DNIS pattern fallback: longest match wins

Business hours and holiday calendars

Verb plans: what the route executes

Caller-ID filter: block and allow at the route edge

Number status: the port-out pending window

The resolution chain

Where the resolution output feeds

Failure edges

Sample trace

See also