# 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](https://support.bandwidth.com/hc/en-us/articles/360014128994-What-MMS-file-types-are-supported-).

:::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](https://support.bandwidth.com/hc/en-us/articles/360035563254-How-do-I-manage-Sub-accounts-and-Locations-in-the-Bandwidth-Dashboard-). Make sure the **Allow user credentials to authenticate API** option is turned on for the account.

  ![The Bandwidth account setting that lets user credentials authenticate the API](/images/pbx/bandwidth-api.png)

- [Purchase the phone number(s)](https://support.bandwidth.com/hc/en-us/articles/360011094753-How-do-I-search-and-order-phone-numbers-) 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.
   :::

   
   ![Cloud Voice, the SMS channel dialog with Bandwidth selected as the ITSP and the webhook URL shown](/images/pbx/webhook-for-bandwidth-pce.png)

## 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](https://support.bandwidth.com/hc/en-us/articles/1500003820522-Registering-brands-and-campaigns-for-10DLC) to keep delivery uninterrupted.
:::

Sign in to the [Bandwidth portal](https://passport.bandwidth.com/login) 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](#step-1-get-the-webhook-url-from-cloud-voice).

   
   ![Cloud Voice, creating a Bandwidth application with the PBX webhook set as the callback](/images/pbx/create-a-bandwidth-application-pce.png)

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

   
   ![Cloud Voice, associating the Bandwidth application with a location](/images/pbx/associate-app-with-location-bandwidth.png)

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

   
   ![Cloud Voice, enabling HTTP SMS and MMS messaging for the Bandwidth location](/images/pbx/enable-http-msg-bandwidth.png)

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

   
   ![Cloud Voice, searching for a number and moving it into the Bandwidth sub-account](/images/pbx/move-number-bandwidth.png)

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

   
   ![Cloud Voice, the Bandwidth page showing the Application ID and Account ID](/images/pbx/note-down-auth-info-on-bandwidth.png)

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

   ![The Bandwidth API Credentials page showing the Client ID and Client Secret](/images/pbx/bandwidth-api-credentials.png)

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

   ![The channel Authentication tab with fields for the Bandwidth application and API credentials](/images/pbx/bandwidth-auth-setting-new.png)

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

      ![The Session Timeout setting for automatically closing idle conversations](/images/pbx/auto-closure-of-conversations.png)

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

      ![The message routing rule dialog with a number field and inbound destination options](/images/pbx/sms-did-number-rule.png)

      - **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 Message Channel list with the new Bandwidth channel showing an active status](/images/pbx/bandwidth-channel-ok.png)

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

  ![The message report showing sent and received counts with a time filter](/images/pbx/message-report.png)

## What to do next

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