Skip to main content
Inbound routes decide where an arriving SMS goes before it reaches the inbox. You define an ordered list of rules; every inbound (MO) message is checked against them, and the first match claims it — everything else keeps its default delivery. It is the messaging analogue of inbound email routing, and it stacks with the per-number SMS routing config. Rules here only govern what an inbound message lands in. They never change how your outbound sends are placed.

​
1. What inbound routes do

A rule is a match condition → destination pair plus a priority number:
  • Match on one of four things. number (the receiving number, normalized E.164 equality), sender (the originating number, same equality), keyword (case-insensitive anywhere in the body), or regex (case-insensitive pattern on the body, validated when you save it).
  • Send the match to a destination. Your own webhook (url, optional HMAC signature with X-Orbit-Signature: sha256=<hex>), a queue, a shared inbox, a team, a templated auto-reply, a stateful SMS menu (SMS-IVR), or an appointment self-service flow (confirm / reschedule / cancel).
  • First match wins. Rules evaluate in ascending priority; ties go to the older rule. No match means the message falls through to default delivery — your inbox still gets it.
Because non-matches are unchanged, you can add rules one at a time and reverse one by disabling it.

​
2. Access

The surface is gated to the owner/admin roles — same permission tier as inbound email routing. Colleagues with lower roles cannot list, create, update, or delete rules in the dashboard or through the API.

​
3. Where it lives

Messages → Settings → Inbound Routes in the dashboard (/messages/settings/inbound-routes). The API surface sits under /api/v1/messages/inbound-routes.

​
4. Define a rule step by step

  1. Open Create rule. Give the rule a name — something that reads well in an audit log later (“Support keyword → helpdesk”, not “Rule 3”).
  2. Set the match. Pick number, sender, keyword, or regex, then enter the value. Regex is checked on save; a bad pattern answers 422 from the API or an inline error in the dashboard instead of silently never matching.
  3. Pick the destination. Webhook needs an HTTPS, publicly reachable URL. For queue/inbox/team, paste the destination’s id. Auto-reply takes the reply text, with {{from}}, {{keyword}}, and {{body}} tokens.
  4. Set priority. Lower numbers evaluate first — leave gaps (10, 20, 30) so you can insert a rule between two neighbors later.
  5. Verify with a sample inbound. Send a matching text from a handset, then check the rule row: Last matched at stamps on a hit, and a failing webhook destination accumulates a failures badge.
  6. Order, pause, remove. Priority is the only ordering knob — move the number to re-sequence. The per-rule switch pauses without deleting; fully remove with the row’s delete action, after which the message falls back to default delivery.

​
5. API parity — CRUD over cURL

All four verbs live under /api/v1/messages/inbound-routes; live keys are prefixed dv_live_sk_:
List rules (evaluation order, webhook secrets masked):
Create a rule — 201:
Update a rule — partial, only the fields you send change:
Delete a rule — defaults take over again:
Full payload fields: name (≤120 chars), matchType, matchValue (≤512 chars), targetType, targetConfig (shape depends on the destination — { url } for webhook, { queueId | inboxId | teamId }, { template } for auto-reply), priority (0–100000, default 100), enabled, and description. A webhook secret (8–256 chars) is write-once: readbacks mask it as ••••.

​
6. When nothing matches

An unmatched inbound goes to the shared inbox exactly as if no rules existed — the rules list never blocks delivery. To see what a rule did, use its counters: a hit stamps Last matched at; a webhook destination that keeps failing shows its failure count on the rule row. The message itself remains readable from the Delivery log and your subscribed webhooks, the same as for unrouted traffic.

​
7. Worked example set

Keyword opt-out routing. Route STOP-style vocabulary to a helpdesk reviewer while built-in opt-out handling still records consent — short codes and brand-specific words stay tenant-owned controls. Match keyword = OPTOUT, target your team’s inbox or queue. (The built-in STOP/opt-in keywords are handled before any rule runs; see keyword auto-reply rules for the consent-recording path.) VIP sender to a priority queue. Match sender = the customer’s handset in E.164, target a queue named vip-support. Both number and sender compare normalized: spaces and dashes collapse before the equality check. Short-code triage with regex. A regex like ^(APPT|BOOK)\b matched against the body can route a family’s appointment keywords to the appointment self-service destination, or to the SMS menu for an interactive prompt tree. Anchored patterns stay faster — the pattern source is capped at 512 characters. Fallback for unrecognized regions. Keep your dashboard’s defaults underneath: put a low-priority catch-all at priority: 90+, and let anything it doesn’t claim fall back to the shared inbox. Operators then see the applied rule stamped on the rule row for every message that matched, and default delivery everywhere else.

​
See also