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

POSThttps://dashboard.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
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

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>

Create a Voice Application

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

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

Examples

Messaging

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>

Voice

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

PATCHhttps://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

PUThttps://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

DELETEhttps://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