{% multimethod %} {% endmultimethod %}

Messaging 2.0 API Setup {#top}

This walks through how to setup your Bandwidth Phone Number API and Bandwidth Voice and Mesasging API to send messages with the new Messaging 2.0 API. This guide is entirely focused on setup with the API. If you'd like to follow along with the UI, head to the via UI to follow along there.

Assumptions

You have downloaded Postman -or- have the ability to make an API request.
- ⚠️ During the Beta, you will HAVE to use Postman, curl, hurl.it or other http tool to create your application ⚠️
You have your Voice and Messaging API userId, token, secret
You have your Phone Number API username and password
You have contacted Support to link your Voice and Messaging API and Phone Number API
You have your Bandwidth Phone Number Dashboard Account Id
You have an existing Sub-account you'd like to use.

Follow along with Postman

Fill out the form on the Postman page to download the Messaging 2.0 collection.

Getting Started

Create application
Create location (sippeer)
Enable SMS on Location (sippeer)
Enable MMS on Location (sippeer)
Assign Application to Location (sippeer)
Order Available Numbers
Check Order Status
Send Text Message

Create application {#create-application}

Save the Application Id After creating the application.

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

{% extendmethod %}

Application Parameters

Request URL

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

Parameters	Mandatory	Description
`ServiceType`	Yes	The type of service the application will be used for `Messaging-V2` is the only valid service type as of February 15, 2018
`AppName`	Yes	Plain text name of the application
`CallbackUrl`	Yes	Url to recieve 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`

{% common %}

Create Application

{% sample lang="http" %}

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

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

{% common %}

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>Messaging-V2</ServiceType>
        <AppName>Production Server</AppName>
        <CallbackUrl>https://yourSecureSite.com/callbacks</CallbackUrl>
        <CallbackCreds>
            <UserId>Your-User-id</UserId>
            <Password>Your-Password</Password>
        </CallbackCreds>
    </Application>
</ApplicationProvisioningResponse>

{% endextendmethod %}

Create location (sippeer) {#create-location}

Save the Location (sippeer) Id After creating the application.

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

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

{% extendmethod %}

Location Parameters

Request URL

POSThttps://dashboard.bandwidth.com/api/accounts/{{account}}/sites/{{subaccount}}/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

{% common %}

Create Location (sippeer)

{% sample lang="http" %}

POST https://dashboard.bandwidth.com/api/accounts/{{account}}/sites/{{subaccount}}/sippeers HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: {user:password}

<SipPeer>
  <PeerName>Bandwidth Messaging 2 test2</PeerName>
  <IsDefaultPeer>true</IsDefaultPeer>
</SipPeer>

{% common %}

Response

HTTP/1.1 201 Created
Location: https://dashboard.bandwidth.com/api/accounts/{{account}}/sites/{{subaccount}}/sippeers/{{location}}

Save the {{location}} from the location header!

{% endextendmethod %}

Enable SMS on Location (sippeer) {#enable-sms-on-location}

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

{% extendmethod %}

Enable SMS Parameters

Request URL

POSThttps://dashboard.bandwidth.com/api/accounts/{{account}}/sites/{{subaccount}}/sippeers/{{location}}/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` Notice the UPPER case `Protocol`
`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`
`ProxyPeerId`	Yest	MUST BE SET TO: `539692`

{% common %}

Enable SMS on Location (sippeer)

{% sample lang="http" %}

POST https://dashboard.bandwidth.com/api/accounts/{{account}}/sites/{{subaccount}}/sippeers/{{location}}/products/messaging/features/sms HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: {user:password}

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

{% common %}

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>

{% endextendmethod %}

Enable MMS on Location (sippeer) {#enable-mms-on-location}

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

{% extendmethod %}

Enable MMS Parameters

Request URL

POSThttps://dashboard.bandwidth.com/api/accounts/{{account}}/sites/{{subaccount}}/sippeers/{{location}}/products/messaging/features/mms

Parameters	Mandatory	Description
`protocol`	Yes	MUST BE SET TO `HTTP` Notice the lower case `protocol`
`ProxyPeerId`	Yest	MUST BE SET TO: `539692`

{% common %}

Enable MMS on Location (sippeer)

{% sample lang="http" %}

POST https://dashboard.bandwidth.com/api/accounts/{{account}}/sites/{{subaccount}}/sippeers/{{location}}/products/messaging/features/mms HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: {user:password}

<MmsFeature>
  <MmsSettings>
    <protocol>HTTP</protocol>
  </MmsSettings>
  <Protocols>
    <HTTP>
      <HttpSettings>
        <ProxyPeerId>539692</ProxyPeerId>
      </HttpSettings>
    </HTTP>
  </Protocols>
</MmsFeature>

{% common %}

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>

{% endextendmethod %}

Assign Application to Location (sippeer) {#assign-application-to-location}

In order to use messaging 2.0 in your account, you need to assign the application created above to the location (sippeer)

{% extendmethod %}

Assign Application Parameters

Request URL

PUThttps://dashboard.bandwidth.com/api/accounts/{{account}}/sites/{{subaccount}}/sippeers/{{location}}/products/messaging/applicationSettings

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

{% common %}

Assign Application to Location (sippeer)

{% sample lang="http" %}

PUT https://dashboard.bandwidth.com/api/accounts/{{account}}/sites/{{subaccount}}/sippeers/{{location}}/products/messaging/applicationSettings HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: {user:password}

<ApplicationsSettings>
  <HttpMessagingV2AppId>299ab22a-d7e6-4cf6-9f4d-2089efc0c031</HttpMessagingV2AppId>
</ApplicationsSettings>

{% common %}

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>299ab22a-d7e6-4cf6-9f4d-2089efc0c031</HttpMessagingV2AppId>
  </ApplicationsSettings>
</ApplicationsSettingsResponse>

{% endextendmethod %}

Order Available Numbers {#order-numbers}

Save the Order Id After creating the order.

Now that you have your account setup to send & receive text messages, you need to order some numbers.

{% extendmethod %}

Order Available Numbers Parameters

Request URL

POSThttps://dashboard.bandwidth.com/api/accounts/{{account}}/orders

Parameters	Mandatory	Description
`AreaCode`	Yes	The area code of the desired numbers. This is just 1 of many ways to search for numbers
`Quantity`	No	Quantity of phone numbers to return, default is `5000`
`SiteId`	Yes	The id of your subaccount (site)
`PeerId`	Yes	The id of your location (sippeer)

{% common %}

Order 1 Available Number

{% sample lang="http" %}

POST https://dashboard.bandwidth.com/api/accounts/{{account}}/orders HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: {user:password}

<Order>
  <AreaCodeSearchAndOrderType>
    <AreaCode>910</AreaCode>
    <Quantity>1</Quantity>
  </AreaCodeSearchAndOrderType>
  <SiteId>{{subaccount}}</SiteId>
  <PeerId>{{location}}</PeerId>
</Order>

{% common %}

Response

HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://dashboard.bandwidth.com/api/accounts/{{account}}/orders/{{order}}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OrderResponse>
  <Order>
    <OrderCreateDate>2017-09-18T17:36:57.274Z</OrderCreateDate>
    <PeerId>{{location}}</PeerId>
    <BackOrderRequested>false</BackOrderRequested>
    <id>a18a8979-ebed-42f0-ae5f-3cfa7941d4c2</id>
    <AreaCodeSearchAndOrderType>
      <AreaCode>910</AreaCode>
      <Quantity>1</Quantity>
    </AreaCodeSearchAndOrderType>
    <PartialAllowed>true</PartialAllowed>
    <SiteId>{{subaccount}}</SiteId>
  </Order>
  <OrderStatus>RECEIVED</OrderStatus>
</OrderResponse>

{% endextendmethod %}

Check Order Status {#check-order-status}

After ordering the numbers, you will need to check on the status to know when those numbers are ready to use.

When the Order Status is COMPLETE : <OrderStatus>COMPLETE</OrderStatus>, the numbers are ready to use

{% extendmethod %}

Check Order Status Parameters

Request URL

GEThttps://dashboard.bandwidth.com/api/accounts/{{account}}/orders/{{order}}

Parameters	Mandatory	Description
`order`	Yes	The ID of the order

{% common %}

Check order status

{% sample lang="http" %}

GET https://dashboard.bandwidth.com/api/accounts/{{account}}/orders/{{order}} HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: {user:password}

{% common %}

Response

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OrderResponse>
  <CompletedQuantity>1</CompletedQuantity>
  <CreatedByUser>lorem</CreatedByUser>
  <LastModifiedDate>2017-09-18T17:36:57.411Z</LastModifiedDate>
  <OrderCompleteDate>2017-09-18T17:36:57.410Z</OrderCompleteDate>
  <Order>
    <OrderCreateDate>2017-09-18T17:36:57.274Z</OrderCreateDate>
    <PeerId>{{location}}</PeerId>
    <BackOrderRequested>false</BackOrderRequested>
    <AreaCodeSearchAndOrderType>
      <AreaCode>910</AreaCode>
      <Quantity>1</Quantity>
    </AreaCodeSearchAndOrderType>
    <PartialAllowed>true</PartialAllowed>
    <SiteId>{{subaccount}}</SiteId>
  </Order>
  <OrderStatus>COMPLETE</OrderStatus>
  <CompletedNumbers>
    <TelephoneNumber>
      <FullNumber>9102398766</FullNumber>
    </TelephoneNumber>
  </CompletedNumbers>
  <Summary>1 number ordered in (910)</Summary>
  <FailedQuantity>0</FailedQuantity>
</OrderResponse>

When the Order Status is COMPLETE: <OrderStatus>COMPLETE</OrderStatus>, the numbers are ready to use

{% endextendmethod %}

Sending Messages {#sending-messages}

To send a message, POST to the /messages endpoint
In the V2 Messaging API, messages are sent asynchronously. Message validation will happen after the server returns 202. API clients should listen for HTTP callback events if they need to track message state after the initial POST request.

{% extendmethod %}

Message Parameters

Request URL

POSThttps://api.catapult.inetwork.com/v2/users/{{userId}}/messages

Parameter	Mandatory	Description
`from`	Yes	One of your telephone numbers the message should come from (should be in E.164 format, like `+19195551212`). The `+1` can be omitted for US numbers in the `from` or `to` parameter
`to`	Yes	The phone number the message should be sent to (must be in E.164 format, like `+19195551212`). The `+1` can be omitted for US numbers in the `from` or `to` parameter
`text`	Yes	The contents of the text message (must be 2048 characters or less).
`applicationId`	Yes	The ID of the Application your `from` number is associated with in the Bandwidth Phone Number Dashboard.

{% common %}

Send Text Message

{% sample lang="http" %}

POST https://api.catapult.inetwork.com/v2/users/{{userId}}/messages HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: {token:secret}

{
  "from"          : "{{your-bandwidth-number}}",
  "to"            : "{{yourTN}}",
  "text"          : "Good morning, this is a test message",
  "applicationId" : "{{your-application-id}}"
}

{% common %}

Response

HTTP/1.1 202
Content-Type: application/json; charset=utf-8

{
  "id"            : "15047516192013g5tuga77zsa6jrp",
  "owner"         : "+19193529968",
  "applicationId" : "05851417-c78b-4636-81a2-014a54d8f119",
  "time"          : "2017-09-07T02:33:39.201Z",
  "direction"     : "out",
  "to"            : ["+19191231234"],
  "from"          : "+19193524444",
  "text"          : "Hi from Bandwidth!"
}

{% endextendmethod %}

Files

apisetup.md

Latest commit

History

apisetup.md

File metadata and controls

Messaging 2.0 API Setup {#top}

Assumptions

Follow along with Postman

Getting Started

Create application {#create-application}

Application Parameters

Request URL

Create Application

Response

Create location (sippeer) {#create-location}

Location Parameters

Request URL

Create Location (sippeer)

Response

Enable SMS on Location (sippeer) {#enable-sms-on-location}

Enable SMS Parameters

Request URL

Enable SMS on Location (sippeer)

Response

Enable MMS on Location (sippeer) {#enable-mms-on-location}

Enable MMS Parameters

Request URL

Enable MMS on Location (sippeer)

Response

Assign Application to Location (sippeer) {#assign-application-to-location}

Assign Application Parameters

Request URL

Assign Application to Location (sippeer)

Response

Order Available Numbers {#order-numbers}

Order Available Numbers Parameters

Request URL

Order 1 Available Number

Response

Check Order Status {#check-order-status}

Check Order Status Parameters

Request URL

Check order status

Response

Sending Messages {#sending-messages}

Message Parameters

Request URL

Send Text Message

Response