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. Requests use OAuth 2.0 bearer token authentication — see Credentials & Authentication to obtain a token.

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

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

Request Parameters

Parameters	Service	Required	Description
`ServiceType`	Both	Yes	The type of service the application will be used for. - `Messaging-V2` for message events - `Voice-V2` for voice events
`AppName`	Both	Yes	Plain text name of the application
`InboundCallbackUrl`	Messaging	Yes, for `Messaging-V2`	Url to receive message events
`OutboundCallbackUrl`	Messaging	Yes, if utilizing status callbacks	Url to receive message events
`InboundCallbackCreds`	Messaging	No, but highly recommended	Basic auth credentials to apply to your inbound message events
`InboundCallbackCreds.UserId`	Messaging	No, but highly recommended	Basic auth `UserId`
`InboundCallbackCreds.Password`	Messaging	No, but highly recommended	Basic auth `Password`
`OutboundCallbackCreds`	Messaging	No, but highly recommended	Basic auth credentials to apply to your outbound message events
`OutboundCallbackCreds.UserId`	Messaging	No, but highly recommended	Basic auth `UserId`
`OutboundCallbackCreds.Password`	Messaging	No, but highly recommended	Basic auth `Password`
`RequestedCallbackTypes`	Messaging	No	List containing the `CallbackTypes` you wish to receive at the `OutboundCallbackUrl`.
`RequestedCallbackTypes.CallbackType`	Messaging	No	`message-delivered`, `message-sending`, `message-failed`, `message-sent`
`CallInitiatedCallbackUrl`	Voice	Yes, for `Voice-V2`	Url to receive initiate events for inbound calls
`CallInitiatedMethod`	Voice	No	HTTP method for events sent to the `CallInitiatedCallbackUrl`. POST or GET Default is POST
`CallStatusCallbackUrl`	Voice	No	Url to receive disconnect events for inbound calls
`CallStatusMethod`	Voice	No	HTTP method for events sent to the `CallStatusCallbackUrl`. POST or GET Default is POST
`CallbackCreds`	Voice	No, but highly recommended	Basic auth credentials to apply to your message & voice events
`CallbackCreds.UserId`	Voice	No, but highly recommended	Basic auth `UserId`
`CallbackCreds.Password`	Voice	No, but highly recommended	Basic auth `Password`
`CallInitiatedFallbackUrl`	Voice	No	Url to receive voice events URL is used when voice events fail to process at `CallInitiatedCallbackUrl`
`CallInitiatedFallbackMethod`	Voice	No	HTTP method for events sent to the `CallInitiatedFallbackUrl`. POST or GET Default is POST
`CallInitiatedFallbackCreds`	Voice	No	Basic auth credentials to apply to voice events sent to the `CallInitiatedFallbackUrl`.
`CallInitiatedFallbackCreds.UserId`	Voice	No	Basic auth `UserId`
`CallInitiatedFallbackCreds.Password`	Voice	No	Basic auth `Password`

Examples

Create a Messaging Application
Create a Voice Application

Request

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

<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-sending</CallbackType>
        <CallbackType>message-sent</CallbackType>
        <CallbackType>message-delivered</CallbackType>
        <CallbackType>message-failed</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-sending</CallbackType>
            <CallbackType>message-sent</CallbackType>
            <CallbackType>message-delivered</CallbackType>
            <CallbackType>message-failed</CallbackType>
        </RequestedCallbackTypes>
    </Application>
</ApplicationProvisioningResponse>

Request

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

<Application>
    <ServiceType>Voice-V2</ServiceType>
    <AppName>Production Server</AppName>
    <CallInitiatedCallbackUrl>https://yourSecureSite.com/callbacks/voice</CallInitiatedCallbackUrl>
    <CallStatusCallbackUrl>https://yourSecureSite.com/callbacks/voice/status</CallStatusCallbackUrl>
    <CallbackCreds>
      <UserId>Your-User-id</UserId>
      <Password>Your-Password</Password>
  </CallbackCreds>
  <CallInitiatedFallbackUrl>https://yourSecureSecondarySite.com/callbacks/voice</CallInitiatedCallbackUrl>
  <CallInitiatedFallbackCreds>
      <UserId>Your-Fallback-User-id</UserId>
      <Password>Your-Fallback-Password</Password>
  </CallInitiatedFallbackCreds>
</Application>

Response

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ApplicationProvisioningResponse>
    <Application>
        <ApplicationId>d775585a-ed5b-4a49-8b96-f68c0a993ebe</ApplicationId>
        <ServiceType>Voice-V2</ServiceType>
        <AppName>Production Server</AppName>
        <CallInitiatedCallbackUrl>https://yourSecureSite.com/callbacks/voice</CallInitiatedCallbackUrl>
        <CallInitiatedMethod>POST</CallInitiatedMethod>
        <CallStatusCallbackUrl>https://yourSecureSite.com/callbacks/voice/status</CallStatusCallbackUrl>
        <CallStatusMethod>POST</CallStatusMethod>
        <CallbackCreds>
            <UserId>Your-User-id</UserId>
        </CallbackCreds>
        <CallInitiatedFallbackUrl>https://yourSecureSecondarySite.com/callbacks/voice</CallInitiatedCallbackUrl>
        <CallInitiatedFallbackMethod>POST</CallInitiatedFallbackMethod>
        <CallInitiatedFallbackCreds>
            <UserId>Your-Fallback-User-id</UserId>
        </CallInitiatedFallbackCreds>
    </Application>
</ApplicationProvisioningResponse>

List Applications

This operation will list all active applications on your account.

Request URL

GEThttps://api.bandwidth.com/api/accounts/{accountId}/applications

Examples

Request

GET https://api.bandwidth.com/api/accounts/{accountId}/applications HTTP/1.1
Authorization: Bearer {YOUR_ACCESS_TOKEN}

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

GEThttps://api.bandwidth.com/api/accounts/{accountId}/applications/{applicationId}

Examples

Messaging
Voice

Request

GET https://api.bandwidth.com/api/accounts/{accountId}/applications/{applicationId} HTTP/1.1
Authorization: Bearer {YOUR_ACCESS_TOKEN}

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-sending</CallbackType>
            <CallbackType>message-sent</CallbackType>
            <CallbackType>message-delivered</CallbackType>
            <CallbackType>message-failed</CallbackType>
        </RequestedCallbackTypes>
    </Application>
</ApplicationProvisioningResponse>

Request

GET https://api.bandwidth.com/api/accounts/{accountId}/applications/{applicationId} HTTP/1.1
Authorization: Bearer {YOUR_ACCESS_TOKEN}

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>Voice-V2</ServiceType>
        <AppName>qMmmTT</AppName>
        <CallInitiatedCallbackUrl>http://example.com</CallInitiatedCallbackUrl>
        <CallbackCreds>
            <UserId>15jPWZmXdm</UserId>
        </CallbackCreds>
        <CallInitiatedFallbackUrl>https://fallback.com</CallInitiatedFallbackUrl>
        <CallInitiatedFallbackMethod>POST</CallInitiatedFallbackMethod>
        <CallInitiatedFallbackCreds>
            <UserId>login2</UserId>
        </CallInitiatedFallbackCreds>
        <CallbackTimeout>20</CallbackTimeout>
    </Application>
</ApplicationProvisioningResponse>

List Sip-Peers associated with an Application

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

Request URL

GEThttps://api.bandwidth.com/api/accounts/{accountId}/applications/{applicationId}/associatedsippeers

Examples

Request

GET https://api.bandwidth.com/api/accounts/{accountId}/applications/{applicationId}/associatedsippeers HTTP/1.1
Authorization: Bearer {YOUR_ACCESS_TOKEN}

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

PATCHhttps://api.bandwidth.com/api/accounts/{accountId}/applications/{applicationId}

Examples

Update only the UserId field

Request

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

<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

PUThttps://api.bandwidth.com/api/accounts/{accountId}/applications/{applicationId}

Examples

Request

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

<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

DELETEhttps://api.bandwidth.com/api/accounts/{accountId}/applications/{applicationId}

Examples

Request

DELETE https://api.bandwidth.com/api/accounts/{accountId}/applications/{applicationId}/associatedsippeers HTTP/1.1
Authorization: Bearer {YOUR_ACCESS_TOKEN}

Response

HTTP 200 OK

Create an Application​

Request URL​

Request Parameters​

Examples​

List Applications​

Request URL​

Examples​

Fetch Specific Application Information​

Request URL​

Examples​

List Sip-Peers associated with an Application​

Request URL​

Examples​

Partially Update an Application​

Request URL​

Examples​

Completely Update an Application​

Request URL​

Examples​

Delete an Application​

Request URL​

Examples​

Create an Application

Request URL

Request Parameters

Examples

List Applications

Request URL

Examples

Fetch Specific Application Information

Request URL

Examples

List Sip-Peers associated with an Application

Request URL

Examples

Partially Update an Application

Request URL

Examples

Completely Update an Application

Request URL

Examples

Delete an Application

Request URL

Examples