Messaging services console

A messaging service is the unifying address for SMS traffic: one id (msvc_…) in place of a bare sender ID, bundling the sender pool, the opt-out list, the inbound webhook, and the throughput cap. Pass that id as messaging_service_id on a send and every message inherits the service’s defaults — you stop repeating from numbers, callback URLs, and STOP/HELP copy per request, and the send pipeline resolves them identically on every call. A bare sender ID (from) controls only which number the message goes out from; the service id controls that plus everything around it. Every field a messaging service carries — the sender pool, the per-country pool map, the opt-out list, the inbound webhook, the behaviour toggles, and the send-rate cap — is editable in the dashboard. This guide first decides whether you need a service at all, then walks the console workflow step by step, then shows a send wired through the service (section 6) and scripts the same lifecycle over the API (section 8); Messaging services — the entity model defines what each field means, and the SMS sending services guide covers the API path end to end.

Create or stay per-channel?

Keep your existing per-channel senders — an alphanumeric sender ID, a long code, or a sender pool passed straight on send requests — when one kind of traffic answers all of these with “no”:

Only one sender serves the channel — there is nothing to rotate.
The platform-default STOP/HELP wording is acceptable; compliance copy is not brand-specific.
Replies either can’t arrive (one-way alphanumeric) or already have a destination. A numeric long code with replies landing in the dashboard inbox qualifies as “has a destination” — don’t create a service just to wire a webhook you already have.
No per-profile throughput ceiling is needed beyond the tenant and carrier limits.

Reach for a service the moment any answer flips: a second sender enters rotation, a second brand needs its own STOP/HELP copy, replies need one stable webhook URL across several numbers, or one traffic lane needs its own send-rate cap. A single-traffic tenant that grows a second sender later can create the service then — sends keep working against a bare from until the first request arrives carrying messaging_service_id. The full construct decision (service vs pool vs inline sender) is scored per traffic pattern in Choosing a sender construct.

1. Route

Open Messages → SMS → Services (/messages/sms/services). The list shows every service on the account with its label and id. New service creates, the row menu edits or deletes, and clicking a service’s label opens its console page with four tabs: Config, Phone numbers, Inbound webhook, and Throughput.

2. Create a service and assign a sender pool

Click New service. The dialog asks for a label (required) and an optional external id — the vendor id you map during a migration, for example a Twilio MGxxx id. As you type an external id, the console looks it up and, if it already belongs to a service on your account, blocks the create and links you to the existing service instead of getting a 409 from the API. Create lands you on the service’s Config tab. Assign the sender pool from the Sender pool picklist — this is the pool that supplies the from number when a send names the service but no sender of its own. Pick None to leave the service without a pool, which is valid: sends then fall through to the sticky conversation sender or the org default. Pool rotation behaviour (sticky, round-robin, random, geomatch) is set on the pool itself — see Sender pools. The same tab sets the Opt-out list picklist (custom STOP/HELP copy and keyword aliases; the platform defaults always merge in) and two numeric ceilings:

Validity period — 0–14400 seconds (up to 4 hours). Leave empty to use the carrier default.
Send-rate cap — 1–1000 messages per second. Leave empty for no per-service cap. The Throughput tab monitors this cap live (section 5).

Per-country routing — sending [country] recipients through a corridor-specific pool instead of the default pool — is an API-only field (country_sender_pools on PATCH /api/v1/messaging/services/:id). It does not appear in the console; the model page covers the map in full.

3. What the console toggles do

The Send behaviour card on the Config tab carries four switches. Each applies to every message sent through this service — these are not fill-in-on-blank defaults like the pool and callback fields.

Toggle	Effect
Sticky sender	Each recipient keeps receiving from the same number, so a two-way conversation stays on one number.
Area-code geomatch	Prefers a sending number whose area code matches the recipient’s. Overrides the pool’s stored pick strategy with geo-matching — the one flag a service pushes into pool resolution.
Smart encoding	Replaces visually-equivalent unicode characters (curly quotes, em-dashes) with GSM-7 counterparts so the message fits a single segment and bills as one.
MMS converter	Re-encodes oversized MMS media inline so it ships within carrier byte limits.

Save Save changes at the bottom of the form — nothing persists until you do. The detail page re-reads the service after each save, so a colleague editing the same service in another tab sees your updated values. For deeper per-flag rationale, see the entity model on Messaging services and the sender-precedence chain on Sender resolution.

4. Wire inbound replies and attach numbers

The Inbound webhook tab decides where replies to this service’s numbers are delivered:

Set the Inbound URL (must be https:// — the field rejects http:// inline rather than on a 422) and pick the HTTP method — POST recommended, GET only for legacy listeners that cannot read a body.
Optionally set a Fallback URL, called once when the primary returns non-2xx after retries, and a Status callback URL for delivery and failure updates on outbound messages.
The second card links to Inbound webhook settings (/developer/webhooks/inbound) where the account-level signing key lives — service-level payloads sign with that key.

The Phone numbers tab is a dual-pane attach/detach surface: the left pane lists numbers already attached to this service, the right pane lists your SMS-capable numbers you could attach. Multi-select rows in either pane and click Attach or Detach (detach asks for confirmation). A right-pane empty state with a Buy numbers link means every owned number is already attached or none exist. Attaching a number that reports no SMS capability is refused with 422 NOT_SMS_CAPABLE — the right pane pre-filters, and the API re-checks.

5. Read the live throughput tab

The Throughput tab shows the already-enforced send-rate engine for this service:

Send rate — accepted messages per second right now, against the configured cap.
Utilization — the percentage of the cap you’re using; turns amber past 70% and red past 90%.
Queue depth — sends held back this second because the cap was reached.
Send rate vs cap chart — the last ~60 one-second samples with a dashed cap line.
Throttle events — counted per window, with the last throttle timestamp; an Active badge means senders are hitting the cap right now.

An admin edits the cap here with Save; Remove cap asks for confirmation. Non-admins see the value read-only with a “Only an admin can change the send-rate cap” note. Over-cap sends are held, not dropped — the send retry queue drains them once the window resets.

6. Send through the service

A send names the service with messaging_service_id; every send request — the unified POST /api/v1/messages and the channel-specific endpoints such as POST /api/v1/messages/sms — accepts that id in place of a bare from. The send pipeline resolves the service once and stamps the resolved sender onto the message, so editing the service later rewrites nothing already sent. An example against the same service the console walkthrough built above (the dashboard’s SMS composer shows the same wiring as a service picklist on the send form):

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

// Same request, any SDK — the helper passes the body through, and the
// messaging service id replaces the from field.
const message = await orbit.request("POST", "/messages/sms", {
  messaging_service_id: "msvc_abc123",
  to: "+14155550199",
  body: "Your Acme Travel trip starts tomorrow.",
});
console.log(message.data.id);     // msg_a1b2…
console.log(message.data.status); // 'queued'

The accepted response is the standard send envelope:

202

{
  "data": {
    "id": "msg_e4d5c6b7a8b9c0d1e2f3a4b5c6d7e8",
    "status": "queued",
    "channel": "sms",
    "segments": 1,
    "encoding": "GSM-7"
  },
  "meta": {
    "request_id": "req_01kc…",
    "timestamp": "2026-09-17T09:18:00.000Z"
  }
}

Two override rules matter when you mix fields:

Request fields beat service defaults. Pass an explicit from and that specific send uses it; every other send through the same id keeps the pool sender. An explicit per-send webhook URL overrides the service’s status_callback the same way — match for Twilio’s MessagingServiceSid contract.
Resolution happens at send time. The sender pool, opt-out list, callbacks, and validity period are read once as the send executes; a config saved a second earlier applies to the next send.

7. Test a service by reference id

If a send integration still references a vendor id (a Twilio MGxxx is the common case), resolve it before routing traffic: paste the id into the create dialog’s External id field. The debounced lookup returns the existing service, and the dialog links you into its console page — use the same check when a migration import claims an id was already ingested. The equivalent API call is GET /api/v1/messaging/services/lookup?external_id=…, and the model page covers the import upsert that external_id keys on.

8. Script the service lifecycle from the API

Everything the console tabs do maps onto POST/PATCH /api/v1/messaging/services — the console is a view over the API, so any field you can click you can also script. The create request below carries everything the PATCH can change at once, but each following sample uses PATCH so the field-by-field shape shows individually.

Create the service, then PATCH its config

A create with the full config plus a follow-up PATCH — each meta block carries request_id and timestamp, matching the standard response envelope:

curl -X POST https://api.orbit.devotel.io/api/v1/messaging/services \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Acme Travel alerts",
    "sender_pool_id": "pool_abc123",
    "opt_out_list_id": "ool_abc123",
    "validity_period_seconds": 3600,
    "mps_cap": 25,
    "sticky_sender": true,
    "area_code_geomatch": true,
    "smart_encoding": true,
    "mms_converter": false,
    "inbound_webhook_url": "https://your-app.example.com/sms/inbound",
    "inbound_method": "POST",
    "fallback_url": "https://your-app.example.com/sms/fallback",
    "status_callback": "https://your-app.example.com/sms/status"
  }'

# Later: change only the toggles and cap — the PATCH is a partial update.
curl -X PATCH https://api.orbit.devotel.io/api/v1/messaging/services/msvc_abc123 \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sticky_sender": false, "mps_cap": 50 }'

import { Orbit } from "@devotel/sdk-node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

// The messaging-services surface is reached through the untyped request
// helper; no typed resource ships for it yet.
const created = await orbit.request("POST", "/messaging/services", {
  label: "Acme Travel alerts",
  sender_pool_id: "pool_abc123",
  opt_out_list_id: "ool_abc123",
  validity_period_seconds: 3600,
  mps_cap: 25,
  sticky_sender: true,
  area_code_geomatch: true,
  smart_encoding: true,
  mms_converter: false,
  inbound_webhook_url: "https://your-app.example.com/sms/inbound",
  inbound_method: "POST",
  fallback_url: "https://your-app.example.com/sms/fallback",
  status_callback: "https://your-app.example.com/sms/status",
});
const serviceId = created.data.id; // msvc_xxx

// PATCH is a partial update — pass only the fields you are changing.
await orbit.request("PATCH", `/messaging/services/${serviceId}`, {
  sticky_sender: false,
  mps_cap: 50,
});

The response echoing every configurable field — the sender pool, the opt-out list, the validity period, the send-rate cap, and the four behaviour toggles:

{
  "data": {
    "id": "msvc_abc123",
    "label": "Acme Travel alerts",
    "sender_pool_id": "pool_abc123",
    "country_sender_pools": {},
    "opt_out_list_id": "ool_abc123",
    "inbound_webhook_url": "https://your-app.example.com/sms/inbound",
    "inbound_method": "POST",
    "fallback_url": "https://your-app.example.com/sms/fallback",
    "status_callback": "https://your-app.example.com/sms/status",
    "sticky_sender": true,
    "area_code_geomatch": true,
    "mms_converter": false,
    "smart_encoding": true,
    "validity_period_seconds": 3600,
    "mps_cap": 25,
    "external_id": null,
    "feature_flags": {},
    "created_at": "2026-09-17T09:12:00.000Z",
    "updated_at": "2026-09-17T09:12:00.000Z"
  },
  "meta": {
    "request_id": "req_01k7…",
    "timestamp": "2026-09-17T09:12:00.412Z"
  }
}

To clear the sender pool, opt-out list, callback URLs, validity period, or cap, PATCH the field back to null. To clear the behaviour toggles, PATCH them to false.

Set the per-country sender-pool map

The one field the console cannot reach — country_sender_pools routes recipients in a given country through that country’s pool instead of the default sender_pool_id. Keys are ISO-3166-1 alpha-2 uppercase; values are pool ids. Replace the whole map per PATCH — there is no per-country merge, and an entry that is missing on the PATCH is removed:

curl -X PATCH https://api.orbit.devotel.io/api/v1/messaging/services/msvc_abc123 \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country_sender_pools": {
      "US": "pool_us_123",
      "GB": "pool_gb_123",
      "DE": "pool_de_123"
    }
  }'

{
  "data": {
    "id": "msvc_abc123",
    "country_sender_pools": {
      "US": "pool_us_123",
      "GB": "pool_gb_123",
      "DE": "pool_de_123"
    }
  },
  "meta": {
    "request_id": "req_01k8…",
    "timestamp": "2026-09-17T09:15:00.201Z"
  }
}

PATCH "country_sender_pools": {} to remove every per-country override and fall back to the default pool for all recipients. A recipient in a country with no entry uses sender_pool_id; a country listed there whose pool id no longer exists falls back the same way.

Attach a number and read live throughput

The console’s Phone numbers and Throughput tabs call these two endpoints:

# Attach a sender DID — 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: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number_id": "pn_abc123" }'

# Detach it again (returns 204).
curl -X DELETE https://api.orbit.devotel.io/api/v1/messaging/services/msvc_abc123/phone-numbers/pn_abc123 \
  -H "X-API-Key: $ORBIT_API_KEY"

# Live throughput — the same gauges the console's Throughput tab polls.
curl https://api.orbit.devotel.io/api/v1/messaging/services/msvc_abc123/throughput-stats \
  -H "X-API-Key: $ORBIT_API_KEY"

# Read or change the cap itself; null clears it.
curl -X PATCH https://api.orbit.devotel.io/api/v1/messaging/services/msvc_abc123/throughput \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mps_cap": 25 }'

// Attach; the response is 201 with the joined row, and repeat attaches are idempotent.
await orbit.request("POST", "/messaging/services/msvc_abc123/phone-numbers", {
  phone_number_id: "pn_abc123",
});

// Detach; returns a 204 with no envelope.
await orbit.request(
  "DELETE",
  "/messaging/services/msvc_abc123/phone-numbers/pn_abc123",
);

// Live send-rate gauges for one service.
const stats = await orbit.request(
  "GET",
  "/messaging/services/msvc_abc123/throughput-stats",
);
console.log(stats.data.current_mps, "of", stats.data.mps_cap, "mps —", stats.data.queue_depth, "queued");

// Set (or clear with null) the per-service cap.
await orbit.request("PATCH", "/messaging/services/msvc_abc123/throughput", {
  mps_cap: 25,
});

The attach response returns the joined row in one shot — id, E.164, and the capability list the console uses to pre-filter:

{
  "data": {
    "messaging_service_id": "msvc_abc123",
    "phone_number_id": "pn_abc123",
    "phone_number": "+14155550199",
    "country_code": "US",
    "capabilities": ["sms", "voice"],
    "attached_at": "2026-09-17T09:17:00.000Z"
  },
  "meta": {
    "request_id": "req_01k9…",
    "timestamp": "2026-09-17T09:17:00.118Z"
  }
}

The throughput-stats response projects the live token-bucket the send path enforces:

{
  "data": {
    "service_sid": "msvc_abc123",
    "label": "Acme Travel alerts",
    "mps_cap": 25,
    "window_second": 1786540210,
    "demand": 31,
    "current_mps": 25,
    "queue_depth": 6,
    "utilization_pct": 100,
    "recent_throttle_count": 6,
    "trailing_throttle_count": 52,
    "last_throttle_at": 1786540210456
  },
  "meta": {
    "request_id": "req_01ka…",
    "timestamp": "2026-09-17T09:30:10.456Z"
  }
}

utilization_pct is null when the service carries no cap; queue_depth is the over-cap sends held for retry this second, not a failure count. GET /messaging/services/throughput-stats (no :id) returns the same shape aggregated across every service on the account.

The SMS-capability gate — 422 NOT_SMS_CAPABLE

Attach refuses a DID whose carrier-reported capabilities contain no sms entry (voice, fax, or MMS only):

422 Error

{
  "error": {
    "code": "NOT_SMS_CAPABLE",
    "message": "This number can't be attached to an SMS messaging service — it has no SMS capability (reports: voice, mms). Attach an SMS-capable number instead.",
    "status": 422,
    "details": {
      "phone_number_id": "pn_abc123",
      "messaging_service_id": "msvc_abc123",
      "capabilities": ["voice", "mms"]
    }
  },
  "meta": {
    "request_id": "req_01kb…",
    "timestamp": "2026-09-17T09:31:00.512Z"
  }
}

The console’s right pane pre-filters such numbers out of the attach list, so this error only reaches scripts. A DID whose capability set is still unknown (empty — not yet reconciled by the carrier sync) attaches; the gate fires only when the carrier reports a non-SMS set.

9. Error states

The console surfaces its own failure modes rather than leaving blank panes:

Symptom	Cause	Recovery
”Couldn’t load this messaging service” banner on the detail page	The API returned an error — the service may have been deleted in another tab	Click Try again; if the banner repeats, return to the list
”Messaging service not found.” empty card	The query settled with no data	Follow Back to messaging services — the list re-reads what exists
”Couldn’t load sender pools” / “Couldn’t load opt-out lists” in the Config tab picklists	The picklist fetch failed, so the dropdown is frozen rather than showing an empty None option	Click Retry; the saved reference stays untouched
”Couldn’t load live throughput.” banner on the Throughput tab	The metrics backend is unreachable	The banner self-recovers once stats flow again; the tab keeps polling
”Only an admin can change the send-rate cap.” on the Throughput tab	Your role is developer or lower	Ask an admin to set the cap; you can still read live stats
”This vendor id is already mapped to …” in the create dialog	The `external_id` resolves to an existing service	Use the inline link to open that service instead of duplicating it

Where the pieces fit

Three decisions sit between a service id and a delivered message:

Question	Decided by	Read
Should this send name a service, a pool, or an inline sender?	You, per traffic lane	Choosing a sender construct
Which sender does a send that names this service actually use?	Sender-resolution precedence — the message’s own fields first, then the service defaults	Sender resolution
Which upstream carries the resolved sender’s traffic — the Devotel wholesale trunk or your own connected carrier?	Your least-cost routing policy, evaluated after sender resolution	Least-cost routing (LCR) policy

The last row only exists if you attach your own upstream: the BYO SMPP carrier lifecycle covers attach, health, and how carrier health feeds the routing policy. Outbound SMS never leaves that boundary — the wholesale trunk plus your own connected carriers. A tenant with no attached carrier can treat the third row as decided.

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

Messaging services console: run the whole lifecycle from the dashboard

Messaging services console

Create or stay per-channel?

1. Route

2. Create a service and assign a sender pool

3. What the console toggles do

4. Wire inbound replies and attach numbers

5. Read the live throughput tab

6. Send through the service

7. Test a service by reference id

8. Script the service lifecycle from the API

Create the service, then PATCH its config

Set the per-country sender-pool map

Attach a number and read live throughput

The SMS-capability gate — 422 NOT_SMS_CAPABLE

9. Error states

Where the pieces fit

See also

​Messaging services console

​Create or stay per-channel?

​1. Route

​2. Create a service and assign a sender pool

​3. What the console toggles do

​4. Wire inbound replies and attach numbers

​5. Read the live throughput tab

​6. Send through the service

​7. Test a service by reference id

​8. Script the service lifecycle from the API

​Create the service, then PATCH its config

​Set the per-country sender-pool map

​Attach a number and read live throughput

​The SMS-capability gate — 422 NOT_SMS_CAPABLE

​9. Error states

​Where the pieces fit

​See also

Messaging services console

Create or stay per-channel?

1. Route

2. Create a service and assign a sender pool

3. What the console toggles do

4. Wire inbound replies and attach numbers

5. Read the live throughput tab

6. Send through the service

7. Test a service by reference id

8. Script the service lifecycle from the API

Create the service, then PATCH its config

Set the per-country sender-pool map

Attach a number and read live throughput

The SMS-capability gate — 422 NOT_SMS_CAPABLE

9. Error states

Where the pieces fit

See also