​

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 defines what each field means, and the SMS sending 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. 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. 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:

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:

​

See also

• Messaging services — the entity model — what each field means, when its defaults fill in, and the per-country pool map
• SMS sending services — the API path for the same lifecycle
• Sender pools — the rotation strategies the service’s pool can use
• Custom Opt-Out Keyword Lists — the STOP/HELP copy a service points at
• Sender resolution — the full precedence chain the service plugs into