Skip to main content

​
Troubleshooting: inbound SMS to your number never arrives

A contact texts one of your SMS-capable numbers and nothing happens on your side: no message in the Inbox, no inbound webhook delivery, and no row you can look up. This page helps you separate a carrier-side non-delivery from a platform-side routing miss — or its repaired form, a temporary routing-map gap that previously let some inbound messages silently disappear — and build the smallest escalation that Support can trace immediately. If an OUTBOUND message you sent is stuck instead, work the delivery-receipt troubleshooting page first — this page covers inbound only.

​
First: confirm the number can receive at all

Inbound SMS only works when both sides of the number are ready:
  1. The number is yours and SMS-capable. In the dashboard, open Numbers and confirm the number shows an Active status and lists SMS among its capabilities. A voice-only number can never receive texts. Note the exact E.164 form shown there (+14155552671).
  2. The sender actually delivered. Have the contact confirm their end shows the message as sent (not failed), and if this is the first inbound message from a new contact or a new country, send one second test text — some carriers suppress the first message to a number that has no prior inbound history on their route.
If the number is not SMS-capable in the dashboard, no inbound SMS can route to you regardless of anything below — change the number or its capabilities before anything else.

​
How inbound routing works (and how it recovers)

For every inbound text, Orbit resolves the destination number to the workspace that owns it before the message enters your Inbox, your inbound webhook, and your responder flows. That resolution is now self-healing:
  • The platform keeps an up-to-date reverse map from each number to its owning workspace, refreshed continuously in the background — on every paid plan and on trial workspaces alike, not only when a subscription is in a particular billing state.
  • When a number was missing from that map (for example right after a bulk import or a number change processed during a maintenance window), inbound messages to it previously had no workspace to land in and could be dropped without an error on either side. With the continuous sweep, such a gap closes by itself within the next cycle, and inbound traffic to the number resumes on its own.
This is the most important behavior change for this symptom class: a routing-map gap is a transient condition that corrects itself. It is a candidate explanation only for messages that arrived before the gap closed; it cannot silently swallow inbound traffic indefinitely.

​
What to check before you escalate

Work these in order — each step narrows the cause class and doubles as an escalation input.
  1. Confirm the exact destination number. Ask the contact to read back the number they texted and compare it to the E.164 form shown on your Numbers page. A sender mistyped one digit, or a short code instead of your long code, means the message never reached Orbit at all.
  2. Search the top-level Messages view. Filter by the contact’s number. If you find the message there but not in the Inbox, routing worked and the issue is inbox assignment — check your responder routing rules and assignment targets, not this page.
  3. Check your inbound webhook subscription. If you expect an event at your own endpoint, confirm the subscription is enabled for inbound message events. A paused or mis-scoped endpoint receives nothing even when the message routed correctly; see the webhook events reference for the event list.
  4. Allow for self-healing on a fresh number. If you just imported or moved numbers, send one more test text now — with the continuous routing-map sweep, a number whose routing had a gap resolves by itself, and only a symptom that persists past that window needs Support.

​
When to escalate, and what to include

Open a support ticket when a test text to an Active, SMS-capable number still never appears after the checks above — or when inbound traffic that worked before stops for more than one number at a time. Include all of these so Support can trace the routing step directly:
  • The destination number in E.164 form, exactly as it appears on your Numbers page.
  • One example sender number and the timestamp of a test message (with timezone).
  • Your tenant ID — in the dashboard under Settings → Organization, and returned by the GET /api/v1/me response as organizationId.
With the number pair and a timestamp, Support can tell within one lookup whether the inbound message reached the platform at all, and whether its routing resolution succeeded.

​
See also