Text-enable a number with hosted messaging

Hosted messaging (also called “Hosted SMS” or “text-enable”) lets a number receive SMS on Orbit while its voice service stays with the current carrier. Instead of porting the number, you open a hosted-messaging order, sign a Letter of Authorization (LOA) authorizing the hosting carrier to overlay SMS routing, and pick where inbound messages land — a webhook URL, an inbox, or a messaging service. This guide walks one number end-to-end: choose → check eligibility → order → LOA → submit → route → activation. Use the API when the steps belong in a pipeline; the dashboard surface at Numbers → Hosted Messaging mirrors the same order lifecycle.

1. Buy, port, or host — pick the path first

Orbit lets a number bring three ways, and the hosted-messaging order is only one of them. Compare the paths before you start, because a full port supersedes a hosted order and buying a fresh number skips the carrier paperwork entirely.

	Buy a number	Port a number	Host a number (this guide)
What moves to Orbit	A brand-new number from the Orbit inventory	Voice + SMS, from your current carrier	SMS routing only
Voice service	New number — no prior carrier	Moves to Orbit with the number	Stays with the current carrier
Number ownership	Orbit provisions it for you	Carrier-of-record changes to the hosting carrier	Carrier-of-record unchanged
Paperwork	None (or a regulatory bundle where required)	LOA + Customer Service Record (CSR)	LOA authorizing SMS overlay
Typical time to active	Minutes	Days to weeks (carrier-dependent)	Minutes of in-platform time + carrier verification
Best for	New campaigns and tracking numbers	Getting a whole number onto Orbit	SMS on a landline, hotline, or voice-locked number

Choose hosted messaging over a port when:

Voice must stay with the losing carrier — a PBX contract, a bundled plan, or a carrier you are contractually locked to.
The number is not voice-portable — some rate centers and country rules block ports while still allowing SMS hosting.
The number is a landline or toll-free you only need for messaging — common for support lines and hotlines.

If you will eventually port the number and voice together, skip hosting and run the port — a port supersedes a hosted order on the same number. For the port path, see Port a number end-to-end; for inventory, see Buy a number. Two hard boundaries to know up front:

Inbound only. Hosted messaging delivers messages the carrier receives on the number. Outbound (MT) SMS on Orbit exits exclusively via the Devotel softswitch — this flow never creates an outbound path.
Voice never moves. If you later want voice + SMS on Orbit, port the number instead; a hosted order is not a step toward a port.

2. Eligibility and prerequisites

Before opening an order, confirm the number qualifies:

Number class — the order accepts landline, tollfree, or mobile. Other classes (short codes, VoIP-assigned numbers) are not eligible.
E.164 format — pass the number as +14155550123, not a national format like (415) 555-0123.
One live order per number — the hosting carrier accepts a single in-flight order per number; a second create attempt returns 409.
API key scope — create/sign/submit/route/cancel calls need the numbers:write scope; list and get need numbers:read. Dashboard sign-in covers both.
LOA signer — the person signing must be authorized on the carrier-of-record account. Have their full legal name and email ready.
Inbound route target — an https:// webhook URL, an inbox id, or a messaging-service id. You can change it until the order activates.

Provide businessName when you create the order — carriers match the LOA against the account holder name on the billing record, and a missing or mismatched name is a common rejection cause.

3. Open the order

From the dashboard, go to Numbers → Hosted Messaging and fill the form: phone number (E.164), voice carrier, number type, and the initial inbound route (webhook HTTPS URL, inbox, or messaging service). The order creates in draft — nothing reaches the carrier yet. The API equivalent:

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14155550123",
    "voiceCarrier": "AT&T",
    "numberType": "landline",
    "businessName": "Acme Inc",
    "inboundRoute": {
      "type": "webhook",
      "target": "https://hooks.example.com/inbound-sms"
    }
  }'

{
  "data": {
    "id": "hostedMessagingOrder_abc123",
    "phoneNumber": "+14155550123",
    "voiceCarrier": "AT&T",
    "numberType": "landline",
    "status": "draft",
    "inboundRoute": {
      "type": "webhook",
      "target": "https://hooks.example.com/inbound-sms"
    },
    "createdAt": "2026-08-24T10:15:00.000Z"
  }
}

A second in-flight order for the same number returns 409 — resolve the existing order (complete, reject, or cancel it) before opening a new one. Cancel any order before a terminal state with DELETE /api/v1/numbers/hosted-messaging/{id}, or with Cancel order in the dashboard.

4. LOA lifecycle — sign, then submit

The LOA authorizes the hosting carrier to add SMS routing to the number. Sign it in-platform (draft → loa_signed), then submit it to the carrier (loa_signed → submitted). In the dashboard, click Sign LOA on the order, record the signer name, email, and acknowledgement, then click Submit to carrier. Submitting before signing is rejected. The API equivalents:

# 1. Record the in-platform signature acknowledgement
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging/hostedMessagingOrder_abc123/loa/sign \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "signerName": "Jane Doe",
    "signerEmail": "jane@acme.com",
    "acknowledgement": "I am authorized to text-enable this number on behalf of the account holder.",
    "loaFileUrl": "https://storage.googleapis.com/orbit-loas/acme/hosted-loa.pdf"
  }'

# 2. Forward the signed order to the hosting carrier
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging/hostedMessagingOrder_abc123/submit \
  -H "X-API-Key: dv_live_sk_..."

loaFileUrl is optional — omit it if ops attaches the LOA artefact out-of-band; when provided, it must be a Devotel-issued storage URL, and the request is rejected otherwise. The acknowledgement text and signer identity are your organization’s authorization record; capture the exact wording the signer accepted so it holds up in a dispute. Signing does not notify the carrier — that buffer lets you revoke (cancel) before submission, the same deliberate break as the porting LOA flow.

5. Set the inbound route

Inbound SMS on the hosted number delivers to the route stored on the order. Change it while the order is draft, loa_signed, or submitted — in the dashboard, edit the route fields on the order; via API:

curl -X PATCH https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging/hostedMessagingOrder_abc123/route \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "inboundRoute": {
      "type": "inbox",
      "target": "inbox_01HZY8Q7"
    }
  }'

Route types:

`type`	`target`
`webhook`	An `https://` URL Orbit POSTs the inbound message to.
`inbox`	An inbox id — the message lands in the shared inbox.
`messaging_service`	A messaging-service id — the message follows that service’s routing.

Once the order is active, the route locks — open a new order to change live routing. A rejected or cancelled order cannot be edited. This lock is deliberate: it keeps the carrier-side hosting config and your delivery target in lock-step.

6. Timeline and status tracking

After submission, the carrier verifies ownership and confirms the hosting overlay. Poll the order — in the dashboard the status badge updates as the carrier responds; via API, GET /api/v1/numbers/hosted-messaging/{id} (or GET .../hosted-messaging for the full list) and read status:

draft → loa_signed → submitted → active
   ↘ cancelled (from any non-terminal state)
   submitted → rejected (carrier/ops refused; see rejectionReason)

`status`	Meaning	Next step
`draft`	Created; no signed LOA yet.	Sign the LOA.
`loa_signed`	Signature recorded; carrier not notified.	Submit to the carrier.
`submitted`	Carrier is verifying ownership.	Wait for `active`; respond to carrier follow-ups.
`active`	SMS hosting confirmed — inbound SMS delivers to your route.	Verify inbound delivery (next section).
`rejected`	Carrier or ops refused the order; `rejectionReason` explains.	Fix the cause and open a new order.
`cancelled`	You stopped the order before activation.	Nothing further.

active, rejected, and cancelled are terminal — every other status has a next action for you. The first two transitions (sign, submit) are you-side and take minutes; the submitted → active wait is carrier verification time and varies with the voice carrier’s response speed. If an order sits in submitted for an unusual stretch, the most common cause is a carrier follow-up — check rejectionReason and your LOA signer contact.

7. Message behavior while hosted

Once active, inbound SMS the receiving carrier delivers on the number arrives on Orbit and follows your stored route:

Routing — webhook targets receive a POST per inbound message; inbox and messaging-service targets surface the message there directly. Hosted numbers deliver inbound only — outbound sending on Orbit stays on its standard path, which is unaffected by the hosted order.
Delivery events — the inbound message carries the same event shape as any other Orbit inbound SMS, so existing webhook receivers and inbox views pick it up with no special handling.
Billing — inbound messages on a hosted number are billed like inbound SMS on any other number in your workspace; the hosting arrangement itself adds no per-message surcharge.
Throughput — the number keeps the inbound throughput characteristics of its number class (landline, toll-free, mobile). If the volume outgrows the number, add more hosted or Orbit numbers behind a messaging service.

If the route type is webhook, treat the receiver like any other inbound-message sink: receive the POST, verify the signature, dedupe on the message id, and return 2xx fast. Follow Webhook consumer for the receiver pattern and Webhook security for signature verification.

8. Reverting a host, or porting later

Hosting is reversible, and it never blocks a later full port:

Before activation — cancel the order (DELETE /api/v1/numbers/hosted-messaging/{id} or Cancel order in the dashboard). The carrier never hosts, and nothing changes on the number.
After activation — inbound SMS keeps delivering to the active route until you open a replacement order or the carrier decommissions the overlay. To move fully to Orbit, run a port per Port a number end-to-end; a full port moves voice + SMS together and supersedes the hosting arrangement on the same number. Cancel the hosted order before the port completes so the carrier is never serving two overlapping requests.
Clean handoff — once the port is active, verify inbound SMS delivers on the ported number, then confirm the hosted order is cancelled.

9. Troubleshooting

Carrier rejects the LOA (status: rejected). Read rejectionReason on the order and fix the LOA content — mismatched account-holder name, a businessName that does not match the billing record, or a signer who is not authorized on the account. Cancel the dead order if needed and open a fresh one with corrected data.
Inbound SMS not arriving after active. Check the route: webhook targets must be reachable https endpoints returning 2xx; inbox/messaging-service targets must be valid ids. Until the order is active the carrier is not yet hosting, so no inbound traffic is expected.
Second order refused with 409. An in-flight order already exists for that number — the hosting carrier only accepts one order per number. Find it via GET .../hosted-messaging and either wait it out or cancel it, then recreate.
Port conflict. If you decide to port the number after all, cancel the hosted order first — a full port supersedes the hosting arrangement, and running both in flight confuses the carrier.
Route locked. You are seeing 409 on route after active — that is by design. Open a new order to change live routing.
422 on the LOA file URL. loaFileUrl must be a Devotel-issued https://storage.googleapis.com/... URL; any other origin is rejected. Omit the field if the signed LOA travels out-of-band.

The full-order checklist: verify E.164 + number class → open order → sign LOA → submit → poll to active → verify inbound → done.

WhatsApp

Developer console

Guides

Messaging Controls

Audience & Support Tools

Text-enable a number with hosted messaging

Text-enable a number with hosted messaging

1. Buy, port, or host — pick the path first

2. Eligibility and prerequisites

3. Open the order

4. LOA lifecycle — sign, then submit

5. Set the inbound route

6. Timeline and status tracking

7. Message behavior while hosted

8. Reverting a host, or porting later

9. Troubleshooting

See Also

​Text-enable a number with hosted messaging

​1. Buy, port, or host — pick the path first

​2. Eligibility and prerequisites

​3. Open the order

​4. LOA lifecycle — sign, then submit

​5. Set the inbound route

​6. Timeline and status tracking

​7. Message behavior while hosted

​8. Reverting a host, or porting later

​9. Troubleshooting

​See Also

Text-enable a number with hosted messaging

1. Buy, port, or host — pick the path first

2. Eligibility and prerequisites

3. Open the order

4. LOA lifecycle — sign, then submit

5. Set the inbound route

6. Timeline and status tracking

7. Message behavior while hosted

8. Reverting a host, or porting later

9. Troubleshooting

See Also