Bandwidth Account API Setup

This walks through how to programmatically setup and configure your Bandwidth account via APIs for use with HTTP Voice and HTTP Messaging

Assumptions

API Authentication

The Account Management API resources are authenticated with your API Credentials for "Number & Account Management".

Getting Started

Next Steps

Once the account has been configured correctly for HTTP Services. See the guides for:

Create Messaging Application

The Application contains the HTTP URL you want to use for both inbound and outbound messages.

Learn more about applications in the documentation.

Application Parameters

Request URL

POSThttps://dashboard.bandwidth.com/api/accounts/{{accountId}}/applications

Request Authentication

The Applications resource is authenticated with your API Credentials for "Number & Account Management"

Parameters Mandatory Description
ServiceType Yes Set to Messaging-V2
AppName Yes Plain text name of the application
MsgCallbackUrl Yes Url to receive all message events
CallbackCreds No Basic auth credentials to apply to your message events
CallbackCreds.UserId No Basic auth UserId
CallbackCreds.Password No Basic auth Password

Create Application

POST https://dashboard.bandwidth.com/api/accounts/{{accountId}}/applications HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<Application>
  <ServiceType>Messaging-V2</ServiceType>
  <AppName>Production Server</AppName>
  <MsgCallbackUrl>https://yourSecureSite.com/callbacks</MsgCallbackUrl>
  <CallbackCreds>
    <UserId>Your-User-id</UserId>
    <Password>Your-Password</Password>
  </CallbackCreds>
</Application>

Response

HTTP/1.1 201 Created
Content-Type: application/xml
Location: https://{baseurl}/accounts/{{accountId}}/applications/{{applicationID}}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ApplicationProvisioningResponse>
  <Application>
    <ApplicationId>{{messaging-applicationId}}</ApplicationId>
    <ServiceType>Messaging-V2</ServiceType>
    <AppName>Production Server</AppName>
    <CallbackUrl>https://yourSecureSite.com/callbacks</CallbackUrl>
    <MsgCallbackUrl>https://yourSecureSite.com/callbacks</MsgCallbackUrl>
    <CallbackCreds>
      <UserId>Your-User-id</UserId>
    </CallbackCreds>
  </Application>
</ApplicationProvisioningResponse>

Create Voice Application

The Application contains the HTTP URL you want to use for inbound calls.

Learn more about applications in the documentation.

Application Parameters

Request URL

POSThttps://dashboard.bandwidth.com/api/accounts/{{accountId}}/applications

Parameters Mandatory Description
ServiceType Yes Set to Voice-V2
AppName Yes Plain text name of the application
CallInitiatedCallbackUrl Yes Url to receive actionable voice events
CallStatusCallbackUrl No Url to receive voice events NOT related to Initiated. Such as: rejected or hung up.
CallbackCreds No Basic auth credentials to apply to your voice events
CallbackCreds.UserId No Basic auth UserId
CallbackCreds.Password No Basic auth Password

Create Application

POST https://dashboard.bandwidth.com/api/accounts/{{accountId}}/applications HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<Application>
  <ServiceType>Voice-V2</ServiceType>
  <AppName>Production Server2</AppName>
  <CallInitiatedCallbackUrl>https://yourSecureSite.com/callbacks/init</CallInitiatedCallbackUrl>
  <CallStatusCallbackUrl>https://yourSecureSite.com/callbacks/status</CallStatusCallbackUrl>
  <CallbackCreds>
    <UserId>Your-User-id</UserId>
    <Password>Your-Password</Password>
  </CallbackCreds>
</Application>

Response

HTTP/1.1 201 Created
Content-Type: application/xml
Location: https://{baseurl}/accounts/{{accountId}}/applications/{{voice-applicationId}}

<ApplicationProvisioningResponse>
  <Application>
    <ApplicationId>{{voice-applicationId}}</ApplicationId>
    <ServiceType>Voice-V2</ServiceType>
    <AppName>Production Server2</AppName>
    <CallInitiatedCallbackUrl>https://yourSecureSite.com/callbacks/init</CallInitiatedCallbackUrl>
    <CallInitiatedMethod>POST</CallInitiatedMethod>
    <CallStatusCallbackUrl>https://yourSecureSite.com/callbacks/status</CallStatusCallbackUrl>
    <CallStatusMethod>POST</CallStatusMethod>
    <CallbackCreds>
      <UserId>Your-User-id</UserId>
    </CallbackCreds>
  </Application>
</ApplicationProvisioningResponse>

Create Sub-Account (site)

This endpoint can be used to create a subaccount (AKA site) on your account

Subaccount Parameters

Request URL

POSThttps://dashboard.bandwidth.com/api/accounts/{{accountId}}/sites

Parameters Mandatory Description
Name Yes The name of the site. Max length of 10 characters
Description No The description of the site
Address Yes The address of the site
CustomerProvidedID No Optional custom ID to assign to your application. Max length of 10 characters
CustomerName No Optional custom name to assign to your application. Max length of 50 characters

Create Sub-Account (site)

POST https://dashboard.bandwidth.com/api/accounts/{{accountId}}/sites HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<Site>
  <Name>BandwidthHQ</Name>
  <Description>Test Gateway</Description>
  <CustomerName>BW</CustomerName>
  <Address>
    <HouseNumber>900</HouseNumber>
    <StreetName>Main Campus Dr</StreetName>
    <City>RALEIGH</City>
    <StateCode>NC</StateCode>
    <Zip>27606</Zip>
    <AddressType>Billing</AddressType>
  </Address>
</Site>

Response

HTTP/1.1 201 Created
Location: https://{baseurl}/accounts/{{accountId}}/sites/{{siteID}}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SiteResponse>
  <Site>
    <Id>29488</Id>
    <Name>BandwidthHQ</Name>
    <Description>Test Gateway</Description>
    <CustomerName>BW</CustomerName>
    <Address>
      <HouseNumber>900</HouseNumber>
      <StreetName>Main Campus Dr</StreetName>
      <City>RALEIGH</City>
      <StateCode>NC</StateCode>
      <Zip>27606</Zip>
      <Country>United States</Country>
      <AddressType>Billing</AddressType>
    </Address>
  </Site>
</SiteResponse>

Create location (sippeer)

The location (sippeer) is a logical grouping of numbers.

  • You'll need a location (sippeer) in order to group phone numbers.

Location Parameters

Request URL

POSThttps://dashboard.bandwidth.com/api/accounts/{{accountId}}/sites/{{siteId}}/sippeers

Parameters Mandatory Description
PeerName Yes Plain text name of the Location (sippeer)
IsDefaultPeer No Boolean:
true
false
The Default SIP Peer is the default "destination" for any Telephone Numbers that are ordered for the Site in which the SIP Peer resides. Each sub-account (site) can have only 1 default SIP Peer. You can configure multiple SIP Peers on a Site

Create Location (sippeer)

POST https://dashboard.bandwidth.com/api/accounts/{{accountId}}/sites/{{siteId}}/sippeers HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<SipPeer>
  <PeerName>Bandwidth 2020-01-06</PeerName>
  <IsDefaultPeer>true</IsDefaultPeer>
</SipPeer>

Response

HTTP/1.1 201 Created
Location: https://{baseurl}/accounts/{{accountId}}/sites/{{siteId}}/sippeers/{{sippeerId}}

Save the from the location header!


Enable SMS on Location (sippeer)

In order to use HTTP messaging in your account, you need to enable SMS and MMS on each location after creating.

Enable SMS Parameters

Request URL

POSThttps://dashboard.bandwidth.com/api/accounts/{{accountId}}/sites/{{siteId}}/sippeers/{{sippeerId}}/products/messaging/features/sms

Parameters Mandatory Description
TollFree Yes Will enable texting to and from toll-free phone numbers.
Boolean:
true
false
ShortCode Yes Will enable texting to and from short codes.
Boolean:
true
false
Protocol Yes MUST BE SET TO HTTP
Zone1 Yes MUST BE SET TO: true
Zone2 Yes MUST BE SET TO: false
Zone3 Yes MUST BE SET TO: false
Zone4 Yes MUST BE SET TO: false
Zone5 Yes MUST BE SET TO: false

Enable SMS on Location (sippeer)

POST https://dashboard.bandwidth.com/api/accounts/{{accountId}}/sites/{{siteId}}/sippeers/{{sippeerId}}/products/messaging/features/sms HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<SipPeerSmsFeature>
  <SipPeerSmsFeatureSettings>
    <TollFree>true</TollFree>
    <ShortCode>true</ShortCode>
    <Protocol>HTTP</Protocol>
    <Zone1>true</Zone1>
    <Zone2>false</Zone2>
    <Zone3>false</Zone3>
    <Zone4>false</Zone4>
    <Zone5>false</Zone5>
  </SipPeerSmsFeatureSettings>
  <HttpSettings />
</SipPeerSmsFeature>

Response

HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SipPeerSmsFeatureResponse>
  <SipPeerSmsFeature>
    <SipPeerSmsFeatureSettings>
      <TollFree>true</TollFree>
      <ShortCode>true</ShortCode>
      <Protocol>HTTP</Protocol>
      <Zone1>true</Zone1>
      <Zone2>false</Zone2>
      <Zone3>false</Zone3>
      <Zone4>false</Zone4>
      <Zone5>false</Zone5>
    </SipPeerSmsFeatureSettings>
    <HttpSettings>
      <ProxyPeerId>539692</ProxyPeerId>
    </HttpSettings>
  </SipPeerSmsFeature>
</SipPeerSmsFeatureResponse>

Enable MMS on Location (sippeer)

In addition to enabling SMS, you must also enable MMS to receive picture messages and other multi-media messages.

Enable MMS Parameters

Request URL

POSThttps://dashboard.bandwidth.com/api/accounts/{{accountId}}/sites/{{siteId}}/sippeers/{{sippeerId}}/products/messaging/features/mms

Parameters Mandatory Description
Protocol Yes MUST BE SET TO HTTP

Enable MMS on Location (sippeer)

POST https://dashboard.bandwidth.com/api/accounts/{{accountId}}/sites/{{siteId}}/sippeers/{{sippeerId}}/products/messaging/features/mms HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<MmsFeature>
  <MmsSettings>
    <Protocol>HTTP</Protocol>
  </MmsSettings>
  <Protocols>
    <HTTP>
      <HttpSettings />
    </HTTP>
  </Protocols>
</MmsFeature>

Response

HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MmsFeatureResponse>
  <MmsFeature>
    <MmsSettings>
      <protocol>HTTP</protocol>
    </MmsSettings>
    <Protocols>
      <HTTP>
        <HttpSettings>
          <proxyPeerId>539692</proxyPeerId>
        </HttpSettings>
      </HTTP>
    </Protocols>
  </MmsFeature>
</MmsFeatureResponse>

Assign Messaging Application to Location (sippeer)

In order to use the messaging API, you need to assign the application created above to the location (sippeer)

Assign Application Parameters

Request URL

PUThttps://dashboard.bandwidth.com/api/accounts/{{accountId}}/sites/{{siteId}}/sippeers/{{sippeerId}}/products/messaging/applicationSettings

Parameters Mandatory Description
HttpMessagingV2AppId Yes The application ID from the application created above

Assign Application to Location (sippeer)

PUT https://dashboard.bandwidth.com/api/accounts/{{accountId}}/sites/{{siteId}}/sippeers/{{sippeerId}}/products/messaging/applicationSettings HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<ApplicationsSettings>
  <HttpMessagingV2AppId>{{messaging-applicationId}}</HttpMessagingV2AppId>
</ApplicationsSettings>

Response

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ApplicationsSettingsResponse>
  <ApplicationsSettings>
    <HttpMessagingV2AppId>{{messaging-applicationId}}</HttpMessagingV2AppId>
  </ApplicationsSettings>
</ApplicationsSettingsResponse>

Assign Voice Application AND Enable HTTP Voice on Location (sippeer)

In addition to enabling SMS & MMS, you must also enable HTTP Voice services on the location to send and receive phone calls. This is done with a single API call to the voice settings endpoint of the location (sippeer).

Bandwidth's voice services and split into two different names:

  • Origination = "inbound calls"
  • Termination = "outbound calls"

Bandwidth requires that both origination (inbound calls) and termination (outbound calls) be set to the same protocol. As such, updating either the "origination" or "termination" settings to HTTP will set the others' setting to the same application.

It is only required to set either termination/settings or origination/settings for configuring HTTP Voice (SIP customers may have different settings). Setting one or the other, will copy the settings to the other settings profile. This example adds and configures the origination/settings, however sending the same request body to the termination/settings will result in the same configuration.

Enable HTTP Voice Parameters

Request URL

POSThttps://dashboard.bandwidth.com/api/accounts/{{accountId}}/sites/{{siteId}}/sippeers/{{sippeerId}}/products/origination/settings

Parameters Mandatory Description
VoiceProtocol Yes MUST BE SET TO HTTP
HttpSettings Yes Parent element for HTTP settings
HttpVoiceV2AppId Yes The applicationId of the Voice application created above

Enable HTTP Voice on Location (via Origination Settings) (sippeer)

POST https://dashboard.bandwidth.com/api/accounts/{{accountId}}/sites/{{siteId}}/sippeers/{{sippeerId}}/products/origination/settings HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<SipPeerOriginationSettings>
  <VoiceProtocol>HTTP</VoiceProtocol>
  <HttpSettings>
    <HttpVoiceV2AppId>{{voice-applicationId}}</HttpVoiceV2AppId>
  </HttpSettings>
</SipPeerOriginationSettings>

Response

HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SipPeerOriginationSettingsResponse>
  <SipPeerOriginationSettings>
    <VoiceProtocol>HTTP</VoiceProtocol>
    <HttpSettings>
      <HttpVoiceV2AppId>{{voice-applicationId}}</HttpVoiceV2AppId>
    </HttpSettings>
  </SipPeerOriginationSettings>
</SipPeerOriginationSettingsResponse>

Ensure HTTP Voice settings on Location (sippeer)

GET https://dashboard.bandwidth.com/api/accounts/{{accountId}}/sites/{{siteId}}/sippeers/{{sippeerId}}/products/termination/settings HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SipPeerOriginationSettingsResponse>
  <SipPeerOriginationSettings>
    <VoiceProtocol>HTTP</VoiceProtocol>
    <HttpSettings>
      <HttpVoiceV2AppId>{{Voice-Application-Id}}</HttpVoiceV2AppId>
    </HttpSettings>
  </SipPeerOriginationSettings>
</SipPeerOriginationSettingsResponse>

results matching ""

    No results matching ""