Skip to main content

​
Hosted messaging: SMS enablement without porting

Hosted messaging (also called “Hosted SMS” or “text-enabling”) makes an existing landline, toll-free, or mobile number SMS-capable without porting it to Orbit. The carrier of record keeps the number and voice service stays exactly where it is; Orbit gets a hosting arrangement with the carrier that lets inbound SMS on the number deliver into your account. This page is the concept model; the request-shape detail lives in the Hosted messaging endpoints, and the step-by-step walkthrough is in Text-enable a number with hosted messaging.

​
Four attachment models

A number can come onto Orbit four ways, and they aren’t interchangeable. Hosted messaging is the model that never moves the number — it adds SMS routing on top of the number’s current carrier instead of replacing that carrier. One capability follows a different attachment model: attaching your own upstream SMS carrier for termination preference (covered in the BYO carrier lifecycle). That model steers which connector outbound SMS rides on; hosted messaging, buy, and port are about which numbers your traffic is addressed to. A hosted number and a BYO carrier are orthogonal — you can use them together, and neither blocks the other. Because a port supersedes a hosted order on the same number, the port-in row and the hosted-messaging row can’t be in flight at once for one DID. Compare the rows above before you open either; if you will eventually bring voice too, skip hosting and go straight to a port.

​
Lifecycle: order → LOA → approval → active → cancel

A hosted-messaging order moves through a deliberate two-step human commitment (you sign, you submit) and a carrier-side verification wait, then either activates or terminates:
This vocabulary mirrors the wider number lifecycle — statuses having a defined next step until they reach a terminal state. The hosted messaging surface names the verbs driving it:
  • POST /api/v1/numbers/hosted-messaging — open the order in draft.
  • POST /api/v1/numbers/hosted-messaging/:id/loa/sign — record the signature.
  • POST /api/v1/numbers/hosted-messaging/:id/submit — forward to the carrier.
  • PATCH /api/v1/numbers/hosted-messaging/:id/route — adjust the route (pre-active).
  • GET /api/v1/numbers/hosted-messaging (+ /:id) — list / fetch the order.
  • DELETE /api/v1/numbers/hosted-messaging/:id — cancel before carrier dispatch.
The one hosted-specific property: until submitted, every transition is yours and takes seconds; submitted → active is carrier time, measured in the voice carrier’s response speed rather than any Orbit SLA.

​
LOA matching: what the signature authorizes

The LOA authorizes the hosting carrier to overlay SMS routing on the number — nothing more. Signing is deliberately decoupled from submitting so you can record authorization and revoke (cancel) before the carrier is ever told, the same deliberate break the porting flow gives you. The signer must be authorized on the carrier-of-record account; capture the verbatim acknowledgement so the record holds up in a dispute.

​
Route lock at activation

The inboundRoute object (webhook / inbox / messaging_service) can be changed until the order is active. Once active the route locks — the carrier-side hosting config and your delivery target must stay in lock-step, so changing live routing means a new order, not an in-place edit.

​
Cancellation restores voice-only

Canceling an order before carrier dispatch returns the number to voice-only exactly as it was — nothing about its voice service was ever touched. A cancel in flight (submitted but not yet active) is the safe revocation point; once active, removal is a separate operation and the carrier holds the overlay until a replacement order or decommission.

​
What inbound and outbound SMS does on a hosted number

The two directions split across the carrier boundary:
  • Inbound (MO). The carrier of record forwards inbound SMS on the hosted number to Orbit at activation. From there the message is identical to any other Orbit inbound SMS — it follows your inboundRoute (a webhook POST, an inbox landing, or a messaging service), and it carries the same event shape your existing receivers already consume, per the MO pipeline model. No special handling is needed at the receiver; the hosted number is a new source address, not a new message plane.
  • Outbound (MT) + DLRs. Outbound SMS on Orbit exits exclusively over the Devotel wholesale softswitch — hosting never creates an outbound path, and it never makes the carrier the sender. Delivery receipts for those sends run through Orbit’s normal DLR planes (DLR lifecycle), unaffected by whether the sending number happens also to be SMS-hosted. A hosted number that you also use as a sender ID behaves exactly like any other number in your inventory: MO lands via the overlay, MT exits via the softswitch, and both reconcile in the one send-side DLR ledger.
Hosted numbers are billed like inbound SMS on any other number in your workspace; the hosting arrangement adds no per-message surcharge. Throughput keeps the number class’s inbound characteristics (landline, toll-free, mobile).

​
Choose hosted messaging over a full port when

Hosting is the right model when the constraint is “voice can’t move”:
  • Voice must stay with the losing carrier — a PBX contract, an enterprise telephony platform, a bundled plan, or a country that gates voice portability.
  • The number is not voice-portable — some rate centers and country rules block ports while still allowing SMS-only hosting.
  • The number is a landline or toll-free you only need for messaging — common for support hotlines and reply-to lines that also receive calls.
If any of these is false and you want the number fully on Orbit (port-out protection, unified billing, one place to manage termination), a port is better — skip the hosted order and start there. And if your end state is a port anyway, opening a hosted order first is wasted paperwork: compare the two rows in the table above before you file.

​
Failure modes

  • Incomplete LOA. A missing signature block, a signer not authorized on the carrier-of-record account, or a missing businessName makes the carrier reject on contact. Read rejectionReason, cancel the dead order, and open a fresh one with corrected data — retries on the same blocked order do not recover.
  • Carrier rejection. The hosting carrier can refuse on eligibility (number class not one of landline / tollfree / mobile, a carrier that does not accept hosting for that DID) or on ownership mismatch (the bill’s account-holder name doesn’t match the LOA). Fix the cause and open a new order; a rejected order is terminal.
  • Duplicate order conflict. A second in-flight order for the same number returns 409 — the carrier accepts only one order per DID. Resolve the existing one (let it complete, or cancel it) before reopening.
  • Cancellation restores voice-only. If the number suddenly stops receiving inbound SMS after an order cancelled, that is by design — the overlay is what was delivering inbound to Orbit; the number’s voice service was never touched.
  • Route locked after activation. A 409 on a route update means the order is active — open a new order to change live routing; this is the lock-step invariant above enforcing itself, not an error.

​
See also