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: 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. Hosted messaging vs. a full port

A hosted-messaging order changes only how SMS on the number is routed — the voice carrier, the existing voice routing, and the carrier-of-record relationship are untouched. A full port moves voice and messaging together (see Port a number end-to-end §9 for where this choice fits in a migration). 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. When to choose it

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 number and voice together, skip hosting and run the port — a port supersedes a hosted order on the same number.

3. Prerequisites

Before opening an order:

API key with the numbers:write scope for create/sign/submit/route/cancel; reads (list, get) need numbers:read.
The number in E.164 format — +14155550123, not a national format.
Number class: landline, tollfree, or mobile.
An inbound route target — an https:// webhook URL, an inbox id, or a messaging-service id. The route can be changed until the order activates.
LOA signer details — the full legal name and email of the party authorized on the carrier-of-record account.

4. Open the order

POST /api/v1/numbers/hosted-messaging creates the order in draft. Provide the number, the carrier of record, the number class, and the initial inbound route. businessName is optional but recommended — carriers match the LOA against the account holder name.

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}.

5. 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). Submitting before signing is rejected.

# 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. 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.

6. 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:

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.

7. Track the order to active

Poll GET /api/v1/numbers/hosted-messaging/{id} (or GET .../hosted-messaging for the full list) and read status:

`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.	Wire/normalize the inbound path (next step).
`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.

8. Wire inbound webhooks

If the route type is webhook, treat it 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. If the route is an inbox or messaging service, inbound messages surface there directly.

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.

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

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Text-enable a number with hosted messaging

Text-enable a number with hosted messaging

1. Hosted messaging vs. a full port

2. When to choose it

3. Prerequisites

4. Open the order

5. LOA lifecycle — sign, then submit

6. Set the inbound route

7. Track the order to active

8. Wire inbound webhooks

9. Troubleshooting

See Also

​Text-enable a number with hosted messaging

​1. Hosted messaging vs. a full port

​2. When to choose it

​3. Prerequisites

​4. Open the order

​5. LOA lifecycle — sign, then submit

​6. Set the inbound route

​7. Track the order to active

​8. Wire inbound webhooks

​9. Troubleshooting

​See Also

Text-enable a number with hosted messaging

1. Hosted messaging vs. a full port

2. When to choose it

3. Prerequisites

4. Open the order

5. LOA lifecycle — sign, then submit

6. Set the inbound route

7. Track the order to active

8. Wire inbound webhooks

9. Troubleshooting

See Also