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

# Messaging services console: run the whole lifecycle from the dashboard

> Create a messaging service, assign its sender pool and opt-out list, set the send-behaviour toggles, wire the inbound webhook, attach numbers, and watch live throughput — all from Messages → SMS → Services in the dashboard.

# Messaging services console

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 covers the console workflow step by step; [Messaging services — the entity model](/concepts/messaging-services-model) defines what each field means, and the [SMS sending services](/guides/sms-services) guide covers the API path.

## 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](/guides/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](/concepts/messaging-services-model) and the sender-precedence chain on [Sender resolution](/concepts/sender-resolution).

## 4. Wire inbound replies and attach numbers

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

1. 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.
2. 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.
3. 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. 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.

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

## See also

* [Messaging services — the entity model](/concepts/messaging-services-model) — what each field means, when its defaults fill in, and the per-country pool map
* [SMS sending services](/guides/sms-services) — the API path for the same lifecycle
* [Sender pools](/guides/sender-pools) — the rotation strategies the service's pool can use
* [Custom Opt-Out Keyword Lists](/guides/opt-out-lists) — the STOP/HELP copy a service points at
* [Sender resolution](/concepts/sender-resolution) — the full precedence chain the service plugs into