Set up a Bandwidth SMS Channel

A Bandwidth SMS (Short Message Service) channel links a Bandwidth phone number to your Cloud Voice system, letting agents handle inbound texts and reply to customers straight from the Cloud Voice App. This page walks you through connecting the two platforms end to end: pulling a webhook from Cloud Voice, wiring the number up in Bandwidth, and then building and configuring the channel on Cloud Voice.

Requirements

Before you start, confirm that your PBX (Private Branch Exchange, the phone system) meets the following:

• Firmware: Version 84.23.0.123 or later.
• Domain name: The PBX domain name must not contain underscore characters. The messaging platform rejects underscores, which leads to authentication failures or a channel that cannot receive messages.
• Domain certificate: A valid domain certificate must be installed. If your Cloud PBX uses a custom root domain rather than a standard Cloud Voice-provided domain, install the certificate before you create the channel. Without it, the channel fails authentication or cannot receive messages.

Supported message types and limits

The Bandwidth channel carries both plain text (SMS) and multimedia (MMS, Multimedia Messaging Service) messages. Which MMS file types are accepted is set by Bandwidth, see Bandwidth’s supported MMS file types.

Caution

When an agent sends multimedia (for example, an image), the messaging provider fetches the file from a link that the PBX generates. If you have an Allowed Country/Region IP Access Protection rule in place, permit inbound access from the country where your messaging provider operates, otherwise the file transfer fails.

The following limits apply:

• File size: 100 MB maximum.
• File retention period: 72 hours.

Prerequisites

Complete these in Bandwidth first:

• Create a sub-account and associate it with your location. Make sure the Allow user credentials to authenticate API option is turned on for the account.

  

• Purchase the phone number(s) you plan to use for messaging.

Step 1: Get the webhook URL from Cloud Voice

Bandwidth needs a callback address to deliver inbound messages to, so grab the PBX webhook URL first.

1. Sign in to the PBX web portal and go to Messaging > Message Channel.

2. Click Add and choose SMS.

3. Open the ITSP (Internet Telephony Service Provider) drop-down, select Bandwidth, then copy the Webhook URL.

   Caution

   The webhook URL regenerates as soon as you leave this page. Always copy and use the current value when you configure Bandwidth.

   

Step 2: Set up the number for SMS in Bandwidth

Caution

Under US A2P 10DLC rules, 10-digit long code numbers used for application-to-person messaging must be registered. Texts sent to US numbers from an unregistered 10DLC number are blocked. If you message US-based customers, confirm the registration requirements with Bandwidth and register your brand and campaign to keep delivery uninterrupted.

Sign in to the Bandwidth portal and work through the following:

1. Create an application under your sub-account and set its callback to the webhook URL you copied from the PBX.

   

2. On the new application’s details page, associate it with your location.

   

3. Enable HTTP SMS and MMS messaging for both the location and the application it’s associated with.

   

4. Find the number you want to use for messaging and move it into your sub-account.

   

5. Record the Application ID and Account ID: you’ll enter both on the PBX.

   

6. Create your API credentials and record them for the PBX integration.

   Caution

   Bandwidth is retiring its legacy Basic Authentication (username and password) in favor of OAuth 2.0 Client Credentials: a Client ID and Client Secret. If you have an existing integration, generate the new OAuth 2.0 credentials in Bandwidth and update them on the PBX before December 1, 2026 to avoid a service interruption.

   Note

   • If you can’t reach the API Credentials page, ask your account admin to grant your user the Credential access role.
   • The Client Secret is shown only once. Copy and store it somewhere safe. If you lose it, you’ll have to rotate it and create a new one.

   

Step 3: Create and configure the channel on Cloud Voice

Now build the channel on the PBX and fill it with the credentials and number you gathered from Bandwidth.

1. Sign in to the PBX web portal and go to Messaging > Message Channel.

2. Click Add and choose SMS.

3. On the Authentication tab, enter your Bandwidth details:

   

   • Name: A label that helps you recognize the channel.
   • ITSP: Select Bandwidth.
   • Application ID: Paste the Application ID from Step 2.
   • Account ID: Enter your Bandwidth Account ID from Step 2.
   • Client ID: Enter the Client ID from your Bandwidth API credentials.
   • Client Secret: Enter the Client Secret from your Bandwidth API credentials.

4. Switch to the Messaging Settings tab and configure the channel:

   1. In Message Sending Rate, set how many messages per second the PBX may send.

      Note

      • If the number of messages to send goes over this value, the PBX queues them and releases them at the set rate.
      • If your rate is higher than the limit your provider allows, messages can fail. Check your account’s rate limit with the provider and raise it if you need to.

   2. Set the session options as needed:

      Setting	What it does
      Close Session Automatically	Select the checkbox to have the system close sessions that have gone idle for a set time, then enter that period in the Session Timeout (Days) field.
      Allow the Creation of Duplicate Active Sessions	Select the checkbox to let a new session start even when an active session already exists between the same sender and receiver. When this is on and an agent tries to open such a session in the Cloud Voice App, a prompt appears; if they continue, the existing session leaves the previous handler’s list and moves to the new agent, carrying the full chat history.

      

   3. In the Number section, click Add to create a message routing rule.

      

      • Number: Enter the purchased number or an Alphanumeric Sender ID.

        Note

        Enter phone numbers in E.164 format, [+][country code][phone number], for example +14102161183.

      • Destination for Inbound Messaging: Choose where incoming messages to this number go:

        Option	What happens
        Extension	Pick an extension from the Extension drop-down. Only that user receives inbound messages from the number.
        Message Queue	Pick a queue from the Message Queue drop-down. Every agent in the queue sees inbound messages for new sessions, but once an agent picks up a session, only they receive its follow-up messages.
        Third-Party Message Analytics Platform (Transmitted via API)	Inbound messages are forwarded automatically to a third-party analytics platform via API (Application Programming Interface) for further processing. This requires your PBX to already be integrated with that platform over the API. Once selected, the PBX transmits inbound messages there, and you can track them through the New Message Notification API event (30031). A full Message API suite is available for richer interaction with the connected platform.

      • Extensions allowed to create messaging sessions: Select the extensions permitted to start a conversation with a customer.

   4. Click Save.

5. Click Save.

Result

• The channel is created and appears in the Message Channel list with a green Status indicator showing it’s active.

  

• The PBX tracks how many messages the channel sends and receives. The Total column counts every message sent, both successful and failed.

  Note

  • The sent count only reflects messages that agents send from the Cloud Voice App. To work out your real cost, ask your provider for the exact number of message segments transmitted, texts longer than 160 characters are split into segments for sending and reassembled on delivery, which inflates the count.
  • Use the time filter to narrow the statistics to a specific period.

  

What to do next

Send a text to the number and confirm the assigned agent receives it in the Cloud Voice App.