How to Get Started with Bandwidth Hosted Messaging

Description Image

Step 1 Create Import Request - Using the Dashboard API

POST to /accounts/{accountId}/externalTns With a list of phone numbers you would like to use Bandwidth for messaging.

Parameter Description Mandatory
CustomerOrderID An order ID created by the customer for their tracking purposes Yes
SiteId The ID of the Site that the Telephone Numbers are to be provisioned to. Yes
SipPeerId The ID of the SIP Peer that the Telephone Numbers are to be provisioned to. No
Action Indentify the action on external TNs. Allowed values... IMPORT or REMOVE. Yes

Example: XML Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ExternalTnsOrder>
    <CustomerOrderID>ICPA123ABC</CustomerOrderID>
    <SiteId>743</SiteId>
    <SipPeerId>303716</SipPeerId>
    <Action>[ IMPORT | REMOVE ]</Action>
    <TelephoneNumbers>
        <TelephoneNumber>9199918388</TelephoneNumber>
        <TelephoneNumber>4158714245</TelephoneNumber>
        <TelephoneNumber>4352154439</TelephoneNumber>
        <TelephoneNumber>4352154466</TelephoneNumber>
    </TelephoneNumbers>
</ExternalTnsOrder>

Example: XML Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ExternalTnsOrderResponse>
    <OrderCreateDate>2016-01-15T11:36:52.727Z</OrderCreateDate>
    <AccountId>1</AccountId>
    <CreatedByUser>jbm</CreatedByUser>
    <OrderId>65e03a35-6b97-48a5-8126-f47bad02df2a</OrderId>
    <ProcessingStatus>RECEIVED</ProcessingStatus>
    <Order>
        <CustomerOrderID>ICPA123ABC</CustomerOrderID>
        <SiteId>743</SiteId>
        <SipPeerId>303716</SipPeerId>
        <Action>[ IMPORT | REMOVE ]</Action>
        <TelephoneNumbers>
            <TelephoneNumber>9199918388</TelephoneNumber>
            <TelephoneNumber>4158714245</TelephoneNumber>
            <TelephoneNumber>4352154439</TelephoneNumber>
            <TelephoneNumber>4352154466</TelephoneNumber>
        </TelephoneNumbers>
    </Order>
</ExternalTnsOrderResponse>

Step 2 Get Status - Using the Dashboard API

Using the the <OrderId> returned in step fetch the <ProcessingStatus> of the order by:

GET to /accounts/{accountId}/externalTns/<{{OrderId}}>

The <ProcessingStatus> has multiple values:

Status Description
RECEIVED Order has yet to be processed, initial status
PROCESSING Order is processing through
COMPLETE Every number requested in the number is now available via Dashboard
PARTIAL Some numbers were procesed, others failed.
Check the <ERRORS> field for more information
FAILED Entire order failed.
Check the <ERRORS> field for more information.

Example: COMPLETE XML Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ExternalTnsOrder>
    <OrderCreateDate>2016-01-15T11:36:52.727Z</OrderCreateDate>
    <AccountId>1</AccountId>
    <CreatedByUser>jbm</CreatedByUser>
    <OrderId>65e03a35-6b97-48a5-8126-f47bad02df2a</OrderId>
    <ProcessingStatus>COMPLETE</ProcessingStatus>
    <Order>
        <CustomerOrderID>ICPA123ABC</CustomerOrderID>
        <SiteId>743</SiteId>
        <SipPeerId>303716</SipPeerId>
        <Action>[ IMPORT | REMOVE ]</Action>
        <TelephoneNumbers>
            <TelephoneNumber>9199918388</TelephoneNumber>
            <TelephoneNumber>4158714245</TelephoneNumber>
            <TelephoneNumber>4352154439</TelephoneNumber>
            <TelephoneNumber>4352154466</TelephoneNumber>
        </TelephoneNumbers>
    </Order>
</ExternalTnsOrder>

Example: PARTIAL XML Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ExternalTnsOrder>
    <OrderCreateDate>2016-01-15T11:36:52.727Z</OrderCreateDate>
    <AccountId>1</AccountId>
    <CreatedByUser>jbm</CreatedByUser>
    <OrderId>65e03a35-6b97-48a5-8126-f47bad02df2a</OrderId>
    <ProcessingStatus>PARTIAL</ProcessingStatus>
    <Order>
        <CustomerOrderID>ICPA123ABC</CustomerOrderID>
        <SiteId>743</SiteId>
        <SipPeerId>303716</SipPeerId>
        <Action>[ IMPORT | REMOVE ]</Action>
        <TelephoneNumbers>
            <TelephoneNumber>9199918388</TelephoneNumber>
            <TelephoneNumber>4158714245</TelephoneNumber>
            <TelephoneNumber>4352154439</TelephoneNumber>
            <TelephoneNumber>4352154466</TelephoneNumber>
        </TelephoneNumbers>
    </Order>
    <Errors>
        <Error>
            <Code>[int]</Code>
            <Description>[string]</Description>
            <TelephoneNumbers>
                <TelephoneNumber>9199918388</TelephoneNumber>
            </TelephoneNumbers>
        </Error>
    </Errors>
</ExternalTnsOrder>

Step 3 Create Application - Using the Bandwidth Communication API

You'll need to configure an application in the Bandwidth Communication API. You may already have an application configured; if so, take note of the applicationId. Otherwise you'll need to create an application.

Parameter Description Mandatory
name A name you choose for this application. Yes
incomingMessageUrl A URL where message events will be sent for an inbound SMS message Yes
incomingMessageUrlCallbackTimeout Determine how long should the platform wait for incomingMessageUrl's response before timing out in milliseconds. No
incomingMessageFallbackUrl The URL used to send the callback event if the request to incomingMessageUrl fails. No
callbackHttpMethod Set to POST to use REST API Control
Set to GET to use BXML Control		 No

Example: Create an application

POST to https://api.catapult.inetwork.com/v1/users/{userId}/applications/

{
  "name": "MyFirstApp",
  "incomingMessageUrl": "http://example.com/messages.php",
  "callbackHttpMethod": "POST"
}

Example Response: 201 - Created

The applicationId is returned in the Location Header.

HTTP/1.1 201 Created
Location: /v1/users/{userId}/applications/{applicationId}

Step 4 Import Number - Using the Bandwidth Communication API

Import numbers with the applicationId from Step 3

Parameter DESCRIPTION Mandatory
Number Dashboard Phone Number being imported. E.164 format. Yes
applicationId HTTP Application you want the phone number to be registered to for inbound messages. Yes
providerName Always use this provider “bandwidth-dashboard” Yes
accountId This ID is associated with your Bandwidth Dashboard account. Note: If you don’t know your Provider Account ID, please open a ticket with our support group. Yes
userName This is your user name used to log into the Bandwidth Dashboard. Yes
password This is your password used to log into the Bandwidth Dashboard. Yes

Example: Import Numbers (One at a time)

You'll need to repeat this process for EVERY number imported in Step 1.

POST to https://api.catapult.inetwork.com/v1/users/{{UserId}}/phoneNumbers

{
  "number": "+14352154439",
  "applicationId":"{{applicationId}}",
  "name" : "text messaging TN",
  "provider": {
    "providerName": "bandwidth-dashboard",
    "properties": {
      "accountId": "9999999",
      "userName": "wileCoyote",
      "password": "catchThatBird"
    }
  }
}

Example Respone: 201 - Created

The numberId is returned in the Location Header.

201 Created
Location:
https://api.catapult.inetwork.com/v1/users/{{UserId}}/phoneNumbers/n-id3x6rblp4jrkih2u7zxjdy

Step 5 Send Message - Using the Bandwidth Communication API

To send a message with your imported number, use the /messaging capabilities as normal.

Example: Send New Message

POST to https://api.catapult.inetwork.com/v1/users/{userId}/messages

{
    "from": "14352154439",
    "to": "{toNumber}",
    "text": "Good morning, this is a test message"
}

Example Respone: 201 - Created

The messageId is returned in the Location Header.

201 Created
Location:
https://api.catapult.inetwork.com/v1/users/{{UserId}}/messages/m-id3x6rblp4jrkih2u7zxjdy

Step 6 Incoming Messages - Using the Bandwidth Communication API

Bandwith will send you either a GET or POST HTTP Callback based on your application configuration in Step 3.

Example GET Callback

All the relevant fields are passed as query parameters

GET http://[External server URL]

/{callbackUrl}?
  messageId=m-asdf&
  from=%2B19191231111&
  eventType=sms&
  text=test&
  time=2016-12-01T16:04:49Z&
  to=%2B14352154439&
  state=received&
  applicationId=a-yr3jpxasdfh5xh5e35saoi&
  direction=in&
  messageUri=https%3A%2F%2Fapi.catapult.inetwork.com%2Fv1%2Fusers%2Fu-123%2Fmessages%2Fm-asdf

Example POST Callback

POST http://[External server URL]

{
   "eventType":"sms",
   "direction":"in",
   "messageId": "{messageId}",
   "messageUri": "https://api.catapult.inetwork.com/v1/users/{userId}/messages/{messageId}",
   "from":"+13233326955",
   "to":"+14352154439",
   "text":"Example",
   "applicationId":"{appId}",
   "time":"2012-11-14T16:13:06.076Z",
   "state":"received"
}

results matching ""

    No results matching ""