SMS sending services

A messaging service is a reusable sender profile: one container that bundles the sender pool (which of your numbers send), the opt-out list (which STOP/HELP keywords and auto-replies apply), and the inbound-reply webhook (where incoming messages land). Once a service exists, you point sends at its id and get the same configuration on every message instead of repeating from numbers and webhook URLs per send. This guide covers the full lifecycle: create a service in the console or with POST /api/v1/messaging/services, attach numbers, wire the opt-out list and inbound webhook, and send through it. For the endpoint shapes, see the Messaging Services API reference; for the sender-pool rotation strategies a service’s pool can use, see Sender pools.

1. When to create a service vs an ad-hoc sender

Create a service when any of these hold:

More than one sender per channel — a single hardcoded from number throttles and burns carrier reputation; a service with a pool rotates senders per recipient.
Branded compliance — if you send under more than one brand, you want that brand’s STOP/HELP copy on every message, not the platform defaults.
Two-way SMS — inbound replies need one webhook URL that every sender number in the service points at.
Migration from Twilio — if you’re mapping a MessagingServiceSid (MGxxx) over, the Orbit service is the equivalent container.

If a send is genuinely one-off (one number, default STOP/HELP copy, no inbound replies), an ad-hoc from is fine. The service exists to stop the “same four fields on every send” repetition once you’re past that.

2. Create a service

In the console

Open Messages → SMS → Services (/messages/sms/services) and click New service. The list page creates, edits, and deletes services; drilling into a service opens its Config, Phone Numbers, and Inbound Webhook tabs. Anything you can do in those tabs is available through the API below on the same service id.

Via the API

Only label is required — the rest of the config attaches later:

curl -X POST https://api.orbit.devotel.io/api/v1/messaging/services \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Acme Travel alerts",
    "sender_pool_id": "pool_abc123",
    "opt_out_list_id": "ool_abc123",
    "inbound_webhook_url": "https://your-app.example.com/sms/inbound"
  }'

The response carries the service’s Orbit id (msvc_xxx), which is what sends reference. Owner or admin scope is required; a duplicate external_id (used for Twilio MGxxx migration) returns 409.

3. Attach numbers, opt-out list, and inbound webhook

Sender numbers

You have two ways to give a service senders, and most services want the pool:

Sender pool (recommended) — set sender_pool_id (or per-country country_sender_pools) so the service resolves from through a named pool’s strategy. See Sender pools for sticky / round_robin / random / geomatch behavior.
Direct phone-number attachment — for a fixed DID rather than a pool, attach specific tenant-owned numbers. SMS-capable DIDs only; voice/MMS-only DIDs are rejected with 422, and re-attaching the same number is idempotent:

curl -X POST "https://api.orbit.devotel.io/api/v1/messaging/services/msvc_abc123/phone-numbers" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number_id": "pn_abc123" }'

A service with no sender at all resolves with a 4xx at send time, so attach at least one before you send through it.

Opt-out (STOP/HELP) list

Set opt_out_list_id on the service to point at a custom list — extra keyword aliases plus branded STOP/HELP/START auto-reply text. The platform’s carrier-mandated defaults always merge in; your list can add to but never remove STOP itself. For list creation and field details, see Custom Opt-Out Keyword Lists. Set opt_out_list_id back to null to fall back to the platform defaults.

Inbound-reply webhook

Set inbound_webhook_url (and optional inbound_method, default POST) so every inbound reply to any sender in the service POSTs to your endpoint. Optional fallback_url and status_callback fields further direct delivery-status events. Webhook URLs are validated server-side to block internal/private addresses — use a public HTTPS URL.

4. Send through the service

Pass messaging_service_id on the message instead of per-field from/webhook values. Any field you set explicitly on the message still wins; the service supplies the rest, matching Twilio’s MessagingServiceSid contract:

curl -X POST https://api.orbit.devotel.io/api/v1/messages \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_service_id": "msvc_abc123",
    "to": "+14155550199",
    "body": "Your Acme Travel trip starts tomorrow."
  }'

The send path resolves the service once at send time and stamps the resolved sender onto the message, so a later edit to the service never retroactively changes already-sent messages. Throughput and routing guardrails (per-service mps_cap, quiet hours, send gates) apply the same way as any other send; per-service mps_cap lets you throttle one profile below the tenant limit.

5. Multi-sender rotation and fallback

Rotation behavior is the sender pool’s strategy, not the service’s — the service just resolves through the pool each send:

sticky keeps a recipient on the same sender so two-way threads stay on one number.
round_robin spreads volume evenly across pool members.
geomatch picks a sender from the recipient’s country when one exists in the pool, falling back to the pool’s remaining senders rather than failing the send.
random rotates statelessly per send.

If every sender in the pool degrades or a pool goes empty, the send fails with a sender-resolution error — fix it from the pool health readout rather than reworking your send code. To preempt, preview which sender a recipient would get (GET /messaging/sender-pools/{id}/preview) before routing traffic.

6. Troubleshooting

Symptom	Likely cause	Fix
`404` creating/updating/sending with a service id	The id is not a messaging service in this tenant (or was deleted)	`GET /api/v1/messaging/services` to list ids; deleted services respond `404` on new sends immediately
`409` on create	`external_id` (Twilio `MGxxx`) already taken by another service in this tenant	Reuse that service, or look it up by `GET /services/lookup?external_id=`
`422 SENDER_POOL_EMPTY` or sender-resolution failure on send	Service has no pool, or the pool has no eligible sender	Attach a pool or a phone number; preview the pool’s sender for a recipient
`422` when attaching a phone number	The DID isn’t SMS-capable (voice/fax/MMS-only)	Attach an SMS-capable DID
Inbound replies never hit your endpoint	`inbound_webhook_url` unset on the service, or the URL failed validation (private/internal address blocked)	Set a public HTTPS webhook on the service
Messages throttled / `429` events on one service	The service’s `mps_cap` is below your send rate	`GET /services/{id}/throughput-stats` to confirm, then raise or clear the cap with `PATCH /services/{id}/throughput`
STOP replies use the generic copy	No `opt_out_list_id` on the service	Attach a custom opt-out list
Edited config not applied	Service cache busts on PATCH; a send during the same second may see the old value	Re-send — the next send reads the update

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

SMS sending services: bundle numbers, opt-out list, and inbound webhook

SMS sending services

1. When to create a service vs an ad-hoc sender

2. Create a service

In the console

Via the API

3. Attach numbers, opt-out list, and inbound webhook

Sender numbers

Opt-out (STOP/HELP) list

Inbound-reply webhook

4. Send through the service

5. Multi-sender rotation and fallback

6. Troubleshooting

See also

​SMS sending services

​1. When to create a service vs an ad-hoc sender

​2. Create a service

​In the console

​Via the API

​3. Attach numbers, opt-out list, and inbound webhook

​Sender numbers

​Opt-out (STOP/HELP) list

​Inbound-reply webhook

​4. Send through the service

​5. Multi-sender rotation and fallback

​6. Troubleshooting

​See also

SMS sending services

1. When to create a service vs an ad-hoc sender

2. Create a service

In the console

Via the API

3. Attach numbers, opt-out list, and inbound webhook

Sender numbers

Opt-out (STOP/HELP) list

Inbound-reply webhook

4. Send through the service

5. Multi-sender rotation and fallback

6. Troubleshooting

See also