Messaging Gateways
A Messaging Gateway is the connection between the platform and an SMS/MMS provider (such as Telnyx, Twilio, or Bandwidth). It carries text messages both ways so your users - and, with the contact center, your queues - can send and receive SMS and MMS on your business phone numbers instead of personal handsets. This screen defines those provider connections; enabling messaging end to end also requires flagging the right numbers and setting up routing.
Bringing SMS online is a three-part effort, spanning both your provider’s portal and Configuration Manager:
- Create a gateway here with the credentials from your provider (below).
- Flag the DIDs/Phone Numbers that are SMS-enabled so the platform knows which numbers can send and receive text.
- Configure Inbound Messaging Routes so inbound messages are delivered to the correct users or queues.
You must also register the platform’s generated webhook URLs (below) in your provider’s portal so inbound messages and delivery receipts reach the platform.
Create/Edit SMS Gateway
Name. Unique alphanumeric name for the SMS Gateway (no spaces or special characters are allowed).
Provider. Name of the SMS service provider. Telnyx, Twilio, Bandwidth, SignalWire, Plivo, Flowroute, MessageBird, Vonage, Infobip, and Sinch are supported out of the box. Choose Custom to connect a provider that is not on the list.
Some entries carry a note saying the provider has not been tested against a live account here. That means the integration was built from the provider’s published API documentation and is covered by automated tests using recorded payloads, but no message has been sent through a real account of that provider by us. Sending, receiving, and delivery reports are all implemented; what has not been ruled out is an error in the provider’s own documentation. If you hit one, it is a quick fix - please report it rather than working around it.
Description. Description of the SMS Gateway, optional.
Domain. Hostname inbound messages and delivery receipts are posted to. When the system has one hostname under Domain and SSL Certificate, this field is filled automatically and is not shown. It appears only if more than one SSL hostname is configured.
The rest of the parameters may be different, and depends on the SMS provider you selected.
Every provider also offers Reject unverified webhooks, described under Verifying inbound webhooks below.
Telnyx
API Key. Provided by Telnyx.
Public key. Your Telnyx account public key, used to verify the signature on inbound webhooks. Copy it from the Telnyx portal under Keys and Credentials; it is not the same as the API key. Verification requires the messaging profile to use webhook API version 2. Leave blank to accept webhooks unverified.
Twilio
Account SID. Provided by Twilio.
Auth Token. Provided by Twilio.
Twilio signs each request with the auth token above, so no additional credential is needed to verify inbound webhooks.
Bandwidth
Application ID. Provided by Bandwidth.
Account ID. Provided by Bandwidth.
Auth Token. Provided by Bandwidth.
API Secret. Provided by Bandwidth.
Callback user and Callback password. Basic authentication credentials that Bandwidth must present on inbound callbacks. Set the same pair as InboundCallbackCreds and OutboundCallbackCreds on your Bandwidth messaging application before saving them here, because Bandwidth is challenged for credentials as soon as a pair exists on the gateway. Both are required; leave both blank to accept callbacks unverified.
SignalWire
Space URL. The base address of your SignalWire Space, for example https://example.signalwire.com. Outbound requests go to your own Space, not to a shared endpoint, so this is required.
Account SID and Auth Token. From the API credentials page of your Space.
Webhook signing key. Used to verify inbound webhooks. This is a separate value from the auth token - SignalWire lists it alongside the API credentials. Leave blank to accept webhooks unverified.
Plivo
Account SID and Auth Token. Plivo calls these the Auth ID and Auth Token; both are on the dashboard overview.
Flowroute
Account SID and Auth Token. Flowroute calls these the Access Key and Secret Key.
Flowroute delivery receipts identify the message but not the phone numbers, so the numbers are taken from the record of the original send. This is automatic and needs no configuration.
MessageBird (Bird)
Auth Token. Your live API key.
Vonage
Account SID and Auth Token. Vonage calls these the API key and API secret. This uses the current Messages API rather than the older SMS endpoint.
Infobip
Provider’s URL. Infobip issues an account-specific base URL, shown on your account’s API page - use that rather than a shared address, or requests will be rejected.
API Key. From the same page.
Sinch
Provider’s URL. The regional base URL for your account, for example https://us.sms.api.sinch.com.
Account SID. Your Sinch service plan ID.
Auth Token. The API token paired with that service plan.
Sinch posts inbound messages and delivery reports to the same address, and the platform tells them apart automatically. Delivery reports are requested per message, so no additional setting is needed on the Sinch side.
Custom
Use Custom when your SMS carrier is not one of the built-in providers. Configuration Manager exposes standard inbound and delivery-status webhooks on the selected domain; your own gateway (or a custom adapter you run) is responsible for sending outbound traffic and forwarding inbound/status events back to those webhooks.
Provider’s URL. Full URL that Configuration Manager submits outbound send requests to. Point this at your own carrier adapter (or, for lab use, at the reference sample gateway).
Account SID. Identifier passed in outbound requests; reused as a generic credential.
Auth Token. Secret paired with Account SID.
Once the gateway is saved, Configuration Manager generates:
- Webhook URL for inbound messages:
https://<domain>/sms/<gateway-name>/generic - Delivery Status URL:
https://<domain>/sms/<gateway-name>/generic/status
For a full setup walkthrough, request/response contracts, and a downloadable Twilio reference adapter you can run locally, see Custom SMS Gateway implementation.
Set URL at a service provider
Once the SMS Gateway is created, Configuration Manager will generate a URL for receiving inbound SMS messages and status information sent by your SMS provider. You need to specify these URLs at your SMS provider’s portal.
Verifying inbound webhooks
An inbound webhook URL is reachable by anyone who learns it, so without verification a third party could post a fabricated message that reaches an agent and is recorded in reporting as genuine. Each provider is verified with whatever mechanism it offers:
| Provider | Verified using | Where the credential comes from |
|---|---|---|
| Telnyx | Ed25519 signature on every request | Public key on the gateway |
| Twilio | Request signature | Auth Token already on the gateway |
| Bandwidth | HTTP Basic authentication | Callback user and Callback password on the gateway |
| SignalWire | Request signature | Webhook signing key on the gateway |
| Plivo, Flowroute, MessageBird, Vonage, Infobip, Sinch | Shared secret in a header or query parameter | Webhook secret on the gateway |
| Custom | Shared secret in a header or query parameter | Webhook secret on the gateway |
Verification starts automatically once the relevant credential is filled in. Until then the gateway keeps working exactly as before, so upgrading changes nothing about existing traffic.
When a request fails verification, the default is to log a warning and still deliver the message. This is deliberate: silently dropping traffic the moment an upgrade lands would be worse than accepting it. Once you have confirmed from the log that verification is succeeding, enable Reject unverified webhooks on the gateway to drop failures instead.
Bandwidth is the one exception to the warn-first behaviour, because Basic authentication works by challenge: Bandwidth deliberately sends the first attempt without credentials and waits for a 401 before retrying with them. Occasional 401 entries in your access log are therefore the normal handshake rather than a fault. The consequence is that filling in Callback user and Callback password takes effect immediately, whether or not rejection is enabled, so configure the matching credentials on the Bandwidth messaging application first. If you fill them in on only one side, callbacks will not be delivered.
Telnyx signatures also carry a timestamp, and requests signed more than five minutes earlier are refused so a captured request cannot be replayed later.
Capturing gateway traffic for troubleshooting
When a provider integration misbehaves, the question is usually whether the provider sent what you expected and whether the platform understood it. Enable Capture traffic for troubleshooting on the gateway to record both sides of that question, then open the capture from the Traffic column in the gateway list.
Each entry shows the exchange twice:
| Column | What it holds |
|---|---|
| Raw payload | Exactly what arrived on the wire, byte for byte, together with the request URL and headers |
| Interpreted as | The message the platform built from that payload - sender, recipient, body, message ID |
| Direction | Whether the exchange came in from the provider or went out to it |
| Type | Whether it was an inbound message, an outbound send, or a delivery status callback |
| Message ID | The provider’s identifier, which is also what links the entry to the matching row in the SMS Log |
Reading the two columns together is what makes a fault obvious. If the raw payload holds the message you expected but Interpreted as is empty, the platform received the request and did not recognise it - a field-mapping problem rather than a provider one. If no entry appears at all, the request never arrived, which points at the provider’s configuration, DNS, or a firewall instead.
This is distinct from the SMS Log report. The SMS Log answers “what happened to this message” for everyday operation and covers all gateways. The capture here answers “what exactly did this gateway and the platform say to each other”, and is meant to be switched on while you diagnose a problem and switched off afterwards.
Two things follow from that intent:
- Entries are removed after 7 days. The capture is not an audit trail, and each entry holds a whole payload.
- Message content is recorded in full, so treat the capture as you would the message bodies themselves. Authentication headers, provider signatures, tokens, and passwords are never recorded, and appear as
[redacted].
When changes take effect
Saving a gateway, an inbound messaging route, a DID, or a WhatsApp account applies the change to the messaging service immediately - there is no service restart to perform and no maintenance window to plan.
As a backstop, the messaging service also re-checks its configuration periodically and picks up anything it has not been told about, so changes made outside the Manager UI - through the REST API, a bulk DID generator run, or a CSV import - take effect on their own within about half a minute rather than waiting for the next restart.
If a change does not seem to have applied, give it a minute before restarting anything, then check the gateway’s captured traffic (below) to see what the provider is actually sending.
Best practices
- Keep provider credentials safe and current. API keys and auth tokens grant full send access on your account (and incur charges). Rotate them at the provider if they are ever exposed, and update the gateway to match.
- Use a domain you control for the webhooks. The Domain field determines the host in the inbound and status URLs your provider posts to; it must be publicly reachable over HTTPS from the provider.
- Enable SMS only on the numbers that need it. Flag the specific DIDs as SMS-enabled rather than assuming every number can text.
- Verify both directions after setup - send a test message out and reply back in - and confirm delivery status is reported, which tells you the status webhook is wired correctly.
- Fill in the verification credential for your provider. Without it the inbound webhook accepts anything that reaches the URL. See Verifying inbound webhooks.
- Turn traffic capture off once you are done with it. Leave it on only while diagnosing a problem; entries hold full message content and expire after 7 days. See Capturing gateway traffic.
Related documentation
- Custom SMS Gateway implementation - connect a provider that is not built in.
- DIDs / Phone Numbers - mark numbers as SMS-enabled.
- Inbound Messaging Routes - deliver inbound messages to users or queues.