Skip to main content

How to manage Applications

Bandwidth uses HTTP webhooks to send message & voice events to any publicly addressable url.

In order to successfully use the Voice & Messaging APIs, you need to configure an Application for both the Voice & the Messaging APIs.

Applications are where you configure webhook URLs for Bandwidth to send either message or voice events to your service.

Each application can be assigned to as many Locations (Sip-Peers) as needed. However, each Location can only be associated with a single Application per service type (Voice or Messaging).

The remainder of this guide covers how to create applications via the API. For a detailed guide to using the UI, please see our account setup guide.

Create an Application

This operation will create an active application.

Request URL

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

Request Parameters

ParametersServiceRequiredDescription
ServiceTypeBothYesThe type of service the application will be used for.

- Messaging-V2 for message events

- Voice-V2 for voice events
AppNameBothYesPlain text name of the application
InboundCallbackUrlMessagingYes, for Messaging-V2Url to receive message events
OutboundCallbackUrlMessagingYes, if utilizing status callbacksUrl to receive message events
InboundCallbackCredsMessagingNo, but highly recommendedBasic auth credentials to apply to your inbound message events
InboundCallbackCreds.UserIdMessagingNo, but highly recommendedBasic auth UserId
InboundCallbackCreds.PasswordMessagingNo, but highly recommendedBasic auth Password
OutboundCallbackCredsMessagingNo, but highly recommendedBasic auth credentials to apply to your outbound message events
OutboundCallbackCreds.UserIdMessagingNo, but highly recommendedBasic auth UserId
OutboundCallbackCreds.PasswordMessagingNo, but highly recommendedBasic auth Password
RequestedCallbackTypesMessagingNoList containing the CallbackTypes you wish to receive at the OutboundCallbackUrl.
RequestedCallbackTypes.CallbackTypeMessagingNomessage-delivered, message-sending, message-failed
CallInitiatedCallbackUrlVoiceYes, for Voice-V2Url to receive initiate events for inbound calls
CallInitiatedMethodVoiceNoHTTP method for events sent to the CallInitiatedCallbackUrl.
POST or GET

Default is POST
CallStatusCallbackUrlVoiceNoUrl to receive disconnect events for inbound calls
CallStatusMethodVoiceNoHTTP method for events sent to the CallStatusCallbackUrl.
POST or GET

Default is POST
CallbackCredsVoiceNo, but highly recommendedBasic auth credentials to apply to your message & voice events
CallbackCreds.UserIdVoiceNo, but highly recommendedBasic auth UserId
CallbackCreds.PasswordVoiceNo, but highly recommendedBasic auth Password
CallInitiatedFallbackUrlVoiceNoUrl to receive voice events URL is used when voice events fail to process at CallInitiatedCallbackUrl
CallInitiatedFallbackMethodVoiceNoHTTP method for events sent to the CallInitiatedFallbackUrl.
POST or GET

Default is POST
CallInitiatedFallbackCredsVoiceNoBasic auth credentials to apply to voice events sent to the CallInitiatedFallbackUrl.
CallInitiatedFallbackCreds.UserIdVoiceNoBasic auth UserId
CallInitiatedFallbackCreds.PasswordVoiceNoBasic auth Password

Examples

Request

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>EBVICs</AppName>
<InboundCallbackUrl>https://example.com</InboundCallbackUrl>
<OutboundCallbackUrl>https://example2.com</OutboundCallbackUrl>
<InboundCallbackCreds>
<UserId>15jPWZmXdm</UserId>
<Password>xxv3jPsPR2</Password>
</InboundCallbackCreds>
<OutboundCallbackCreds>
<UserId>15jPWZmXdm</UserId>
<Password>xxv3jPsPR2</Password>
</OutboundCallbackCreds>
<RequestedCallbackTypes>
<CallbackType>message-delivered</CallbackType>
<CallbackType>message-failed</CallbackType>
<CallbackType>message-sending</CallbackType>
</RequestedCallbackTypes>
</Application>

Response

HTTP/1.1 201 Created
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ApplicationProvisioningResponse>
<Application>
<ApplicationId>d4d1b41d-4c05-47d0-838a-34e4f14e4e3e</ApplicationId>
<ServiceType>Messaging-V2</ServiceType>
<AppName>EBVICs</AppName>
<InboundCallbackUrl>https://example.com</InboundCallbackUrl>
<OutboundCallbackUrl>https://example2.com</OutboundCallbackUrl>
<InboundCallbackCreds>
<UserId>15jPWZmXdm</UserId>
</InboundCallbackCreds>
<OutboundCallbackCreds>
<UserId>15jPWZmXdm</UserId>
</OutboundCallbackCreds>
<RequestedCallbackTypes>
<CallbackType>message-delivered</CallbackType>
<CallbackType>message-failed</CallbackType>
<CallbackType>message-sending</CallbackType>
</RequestedCallbackTypes>
</Application>
</ApplicationProvisioningResponse>

List Applications

This operation will list all active applications on your account.

Request URL

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

Examples

Request

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/applications HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP/1.1 200 OK
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ApplicationProvisioningResponse>
<ApplicationList>
<Application>
<ApplicationId>2cfcb382-161c-46d4-8c67-87ca09a72c85</ApplicationId>
<ServiceType>Messaging-V2</ServiceType>
<AppName>app1</AppName>
<InboundCallbackUrl>http://example.com/messaging/inbound</InboundCallbackUrl>
</Application>
<Application>
<ApplicationId>0cb0112b-5998-4c81-999a-0d3fb5e3f8e2</ApplicationId>
<ServiceType>Voice-V2</ServiceType>
<AppName>app2</AppName>
<CallInitiatedCallbackUrl>http://example.com/voice/inbound</CallInitiatedCallbackUrl>
<CallbackCreds>
<UserId>15jPWZmXdm</UserId>
</CallbackCreds>
<CallInitiatedFallbackUrl>https://fallback.com</CallInitiatedFallbackUrl>
<CallInitiatedFallbackMethod>POST</CallInitiatedFallbackMethod>
<CallInitiatedFallbackCreds>
<UserId>login2</UserId>
</CallInitiatedFallbackCreds>
<CallbackTimeout>20</CallbackTimeout>
</Application>
</ApplicationList>
</ApplicationProvisioningResponse>

Fetch Specific Application Information

This operation will list information for a single active application on your account.

Request URL

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/applications/{ applicationId }

Examples

Request

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/applications/{applicationId} HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP/1.1 200 OK
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ApplicationProvisioningResponse>
<Application>
<ApplicationId>e5a9e103-097e-4ec4-87a0-50109fb7b4b1</ApplicationId>
<ServiceType>Messaging-V2</ServiceType>
<AppName>qMmmTT</AppName>
<InboundCallbackUrl>https://example.com</InboundCallbackUrl>
<OutboundCallbackUrl>https://example2.com</OutboundCallbackUrl>
<InboundCallbackCreds>
<UserId>15jPWZmXdm</UserId>
</InboundCallbackCreds>
<OutboundCallbackCreds>
<UserId>15jPWZmXdm</UserId>
</OutboundCallbackCreds>
<RequestedCallbackTypes>
<CallbackType>message-delivered</CallbackType>
<CallbackType>message-failed</CallbackType>
<CallbackType>message-sending</CallbackType>
</RequestedCallbackTypes>
</Application>
</ApplicationProvisioningResponse>

List Sip-Peers associated with an Application

This operation will list the associated Sip-Peers (Locations) with a specific applicaton.

Request URL

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/applications/{ applicationId }/associatedsippeers

Examples

Request

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/applications/{applicationId}/associatedsippeers HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP/1.1 200 OK
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssociatedSipPeersResponse>
<AssociatedSipPeers>
<AssociatedSipPeer>
<SiteId>13651</SiteId>
<SiteName>Prod Sub-account</SiteName>
<PeerId>540341</PeerId>
<PeerName>Prod</PeerName>
</AssociatedSipPeer>
<AssociatedSipPeer>
<SiteId>13622</SiteId>
<SiteName>Dev Sub-zccount</SiteName>
<PeerId>540349</PeerId>
<PeerName>Dev</PeerName>
</AssociatedSipPeer>
</AssociatedSipPeers>
</AssociatedSipPeersResponse>

Partially Update an Application

danger

Once the application ServiceType has been set - it can not be changed.

Request URL

PATCH https://dashboard.bandwidth.com/api/accounts/{accountId}/applications/{ applicationId }

Examples

Update only the UserId field

Request

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

<Application>
<CallbackCreds>
<UserId>Your-NEW-User-id</UserId>
</CallbackCreds>
</Application>

Response

HTTP/1.1 200 OK
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ApplicationProvisioningResponse>
<Application>
<ApplicationId>d775585a-ed5b-4a49-8b96-f68c0a993ebe</ApplicationId>
<ServiceType>Messaging-V2</ServiceType>
<AppName>Production Server</AppName>
<InboundCallbackUrl>https://example.com</InboundCallbackUrl>
<CallbackCreds>
<UserId>Your-NEW-User-id</UserId>
<Password>Your-Password</Password>
</CallbackCreds>
</Application>
</ApplicationProvisioningResponse>

Completely Update an Application

danger

Once the application ServiceType has been set - it can not be changed.

Request URL

PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/applications/{ applicationId }

Examples

Request

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

<Application>
<AppName>Production Server</AppName>
<InboundCallbackUrl>https://example.com</InboundCallbackUrl>
</Application>

Response

HTTP/1.1 200 OK
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ApplicationProvisioningResponse>
<Application>
<ApplicationId>d775585a-ed5b-4a49-8b96-f68c0a993ebe</ApplicationId>
<ServiceType>Messaging-V2</ServiceType>
<AppName>Production Server</AppName>
<InboundCallbackUrl>https://example.com</InboundCallbackUrl>
</Application>
</ApplicationProvisioningResponse>

Delete an Application

This operation will delete an active application.

Request URL

DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/applications/{ applicationId }

Examples

Request

DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/applications/{applicationId}/associatedsippeers HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP 200 OK