Skip to main content

Bandwidth

Vodia connects to Bandwidth for SMS and MMS using OAuth 2.0 (client credentials). Before configuring Vodia, gather your Bandwidth credentials as described below.

Authentication (OAuth 2.0)​

Bandwidth no longer supports API username and password authentication for the Messaging API. You must create an OAuth API credential in the Bandwidth dashboard with access to the Messaging API. Bandwidth will issue a:

  • Client ID
  • Client Secret

Copy the Client Secret when it is shown. Bandwidth may not display it again. Refer to the Bandwidth dashboard documentation for the exact location of API credential settings.

You will also need:

  • Your Bandwidth Account ID
  • The Messaging Application ID that your number is assigned to

How Vodia uses the credential​

  1. Vodia requests an access token from https://api.bandwidth.com/api/v1/oauth2/token using your Client ID and Client Secret.
  2. Bandwidth returns a short-lived access token.
  3. Vodia sends outbound messages using this token as a Bearer token.
  4. The token is cached and refreshed automatically shortly before it expires. No manual token management is required.
note

Your PBX must be able to reach api.bandwidth.com and messaging.bandwidth.com over HTTPS (port 443).

Upgrading from username/password authentication

Earlier versions of this integration used a Bandwidth API username and password. If you are upgrading, create an OAuth credential as described above and update the provider settings below. Legacy API user credentials will not work.

Add an SMS provider​

  • Log into your Vodia Tenant portal.
  • Click Trunks on the left menu, then SMS Management.
  • Under the Providers tab, click the [+ | Add] button.
  • Complete the following fields:
FieldValue
NameA name for your reference, e.g. Bandwidth
ProviderSelect Bandwidth
Username or accountYour Bandwidth Account ID, e.g. 5000001
Application tokenYour OAuth Client ID, e.g. a9f3c2e1-1234-5678-9abc-def012345678
Application IDYour Messaging Application ID, e.g. a1b2c3d4-0000-1111-2222-333344445555
Application secretYour OAuth Client Secret
Explicitly list addresses for inbound trafficOptional (see below)
note

All four credential fields are required. Application token takes the OAuth Client ID, not an access token. Vodia generates access tokens automatically.

Explicitly list addresses for inbound traffic​

Optionally, restrict which IP addresses may deliver inbound webhooks for this provider. If you use this, enter Bandwidth's published webhook source addresses. Leave blank to accept inbound callbacks from any address.

  • Click [Save].

Add your SMS numbers​

  • Under Trunks → SMS Management, click the Numbers tab and click the [+ | Add] button.
  • Name: A name for your reference.
  • Number: Enter your phone number in the format that matches your Bandwidth configuration (typically E.164, e.g. +12025551234). Numbers are passed to Bandwidth as-is.
  • Policy: Select a policy if you have one in place (optional).
  • Provider: Select the Bandwidth provider you created above.
  • URL prefix for receiving messages: Enter a prefix for your inbound callback URL, e.g. bandwidthinbound.
  • Source: e.g. your extension number.
  • Destination: e.g. your extension number.
  • Click [Save].

Configure the Bandwidth inbound webhook​

To receive SMS and MMS, configure your Bandwidth Messaging Application to send inbound message callbacks to your PBX. Refer to the Bandwidth dashboard documentation for the exact location of these settings.

  1. Set the Inbound Callback URL (Messaging Callback URL) on the Messaging Application to your PBX URL plus the prefix you chose above, for example: https://your-pbx-domain.com/bandwidthinbound
  2. Confirm the Application ID entered in the Vodia provider matches the Messaging Application your number is assigned to.

Bandwidth delivers inbound events as a JSON array. Vodia handles message-received events (delivering the SMS/MMS to the destination) and logs message-delivered and message-failed status events.

MMS / media​

Outbound: When a message includes media, Vodia passes the media URL to Bandwidth in the send request.

Inbound: Vodia downloads media from the Bandwidth media URL using your configured credentials. Supported inbound media types are JPG, JPEG, PNG, and PDF.

Troubleshooting​

  • Messages fail to send: Check the PBX log for Bandwidth error: entries. No access_token in token response usually means the Client ID (Application token) or Client Secret (Application secret) is wrong, or the credential lacks Messaging API access.
  • Inbound messages not arriving: Confirm the callback URL in Bandwidth matches your PBX domain and URL prefix exactly. If you set Explicitly list addresses for inbound traffic, confirm Bandwidth's source addresses are included.
  • Wrong application: Confirm the Application ID in the Vodia provider matches the Messaging Application your number is assigned to.

Your Bandwidth SMS integration is now configured and ready to use.