> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted messaging: SMS enablement without porting

> Hosted messaging (text-enable) is the fourth attachment model — it makes an existing landline, toll-free, or mobile number SMS-capable while its voice service and carrier-of-record stay unchanged. Covers the order lifecycle, inbound and outbound SMS behavior, when to choose it over a full port, and the failure modes.

# 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](/api-reference/numbers#hosted-messaging), and the step-by-step
walkthrough is in [Text-enable a number with hosted
messaging](/guides/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.

| Model                                                            | What changes                                    | Carrier of record              | Who terminates voice |
| ---------------------------------------------------------------- | ----------------------------------------------- | ------------------------------ | -------------------- |
| **Buy** ([Search and purchase](/numbers/overview))               | A brand-new number provisions onto your account | New inventory from Orbit       | Orbit                |
| **Port-in** ([Number porting](/numbers/porting))                 | Voice + SMS both migrate to Orbit               | Changes to Orbit               | Orbit                |
| **Port-out** ([Port-out model](/concepts/number-port-out-model)) | Voice + SMS migrate away to a new carrier       | Changes to the winning carrier | The winning carrier  |
| **Hosted messaging** (this page)                                 | SMS-only overlay on the existing number         | Unchanged                      | The current carrier  |

One capability follows a different attachment model: attaching your own
upstream SMS carrier for **termination preference** (covered in the [BYO
carrier lifecycle](/concepts/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:

```
draft → loa_signed → submitted → active
   ↘ cancelled (from any non-terminal state, before carrier dispatch is irrevocable)
   submitted → rejected (carrier or operations refused; rejectionReason explains)
```

| Status       | Meaning                                                                | Next step                          |
| ------------ | ---------------------------------------------------------------------- | ---------------------------------- |
| `draft`      | Order created; awaiting the signed LOA. The carrier is never notified. | Sign the LOA.                      |
| `loa_signed` | Authorization recorded; carrier not yet told.                          | Submit to the carrier.             |
| `submitted`  | Signed order forwarded; carrier begins ownership verification.         | Wait for `active` (or `rejected`). |
| `active`     | Hosting confirmed — inbound SMS routes per `inboundRoute`.             | Verify inbound delivery.           |
| `rejected`   | Carrier or operations refused. `rejectionReason` names the blocker.    | Fix the cause; open a new order.   |
| `cancelled`  | You stopped the order before activation. The number stays voice-only.  | Nothing further.                   |

This vocabulary mirrors the wider [number lifecycle](/numbers/lifecycle) —
statuses having a defined next step until they reach a terminal state. The
[hosted messaging surface](/api-reference/numbers#hosted-messaging) 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](/numbers/porting#2-attach-a-signed-letter-of-authorization-loa)
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](/concepts/dlr-and-mo-pipeline). 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](/concepts/delivery-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

* [Text-enable a number with hosted messaging](/guides/hosted-messaging) —
  the end-to-end walkthrough this page defined.
* [Hosted messaging endpoints](/api-reference/numbers#hosted-messaging) —
  request/response shapes for every verb in the lifecycle.
* [Number portability model](/concepts/number-portability-model) — the full
  port model a hosted order supersedes when both are in flight.
* [BYO carrier lifecycle](/concepts/byo-carrier-lifecycle) — the outbound
  termination-preference model that pairs orthogonally with hosting.
* [Number lifecycle](/numbers/lifecycle) — status vocabulary across all
  attachment models.