How do I set up a Messaging API account in the Bandwidth Dashboard?

Before we get started

Have you downloaded Postman or have the ability to make an API request? Postman is an app for easy RESTful API exploration. In this guide, we'll use Postman to send messages using our new application.

Once you’ve downloaded Postman and created an account (if you don’t already have one), open the Postman Collection.

In order to send messages with Bandwidth, you’ll need several pieces of information that can be located in the Bandwidth Dashboard:

Username and password

These are your credentials to log into the Bandwidth Dashboard.

Account ID

You can locate your Account ID on the Account Overview page in the Bandwidth Dashboard. Simply click Account in the top navigation bar and then select Overview.

Sub-Account 

If you have an existing Sub-Account, click Account in the top navigation bar and then select Sub-Accounts. You'll see the Sub-Account ID next to the Sub-Account name on the left side of this screen. Enter this ID into the Postman form.

Messaging API Token and Secret

Bandwidth APIs use BASIC HTTP Authentication. You'll need to have your Account ID, Token, and Secret to make API calls. You may already have a Token and Secret that you can enter into the Postman form, but if you need a new set of credentials, perform the following steps:

1. In the Bandwidth Dashboard, navigate to the Applications menu. In the top right of your screen, you’ll see a link for API credentials.

2. Click Create New and then copy the credentials into a safe place for future use. Token and Secret pairs won't be visible after you leave this screen.

Create an Application

Now that we’ve taken care of the prerequisites, we’re ready to create an Application:

1. In the top navigation bar of the Bandwidth Dashboard, click Applications and then select Create New. 
2. Enter your Application name.
3. Your Application ID is created for you.
4. Enter your Callback URL (this is the URL of your server).
5. Click Create Application.

Create a Location

Once you’ve created your Application, we’ll need to associate it with a Location. If you have an existing Location, choose the Associate a location with this application link. If not, you’ll need to click the link to add a Location.

You can read more about the steps for creating your Location in our support article.

To create a Location, perform the following steps

1. In the top navigation bar of the Bandwidth Dashboard, click Account and then click Locations.
2. Select Add Location.
3. Select the Sub-Account that the Location will be associated with.
4. Enter your Location name.
5. Select the SMS and MMS settings appropriate for your account.
6. When selecting HTTP Messaging (if your SMS Protocol is HTTP), please use the drop-down to assign the Application you just created to this Location.
7. After selecting all of the appropriate settings for your Location, click Submit.

Order phone numbers

1. Now that we’ve done all the setup work for our application, we need to order a phone number to use to send text messages.
2. Once your order/purchase has been completed, you'll land on the New Number Order Details page. 
3. Scroll down the page till you see the number you ordered and use the Copy to Clipboard button to grab the number. This is the number you'll use to send and receive messages with your Application. 

Fill in the Postman Collection's environment variables

Now you’ve gathered all the information needed to complete the Postman Collection environment variables. 

1. Select Collections to view the collection in Postman.
2. Click the three dots highlighted in the screenshot below and select Edit.

3. You'll see a window pop up as shown in the screenshot below. Navigate to the Variables tab.

4. Fill in the information under the Current Value fields. Postman will use these variables to fill in the relevant fields of your request. Once the variables are filled in, select Update.
   • accountId: your account ID
   • apiToken: your Bandwidth messaging Token
   • apiSecret: your Bandwidth messaging Secret
   • messagingApplicationId: your Bandwidth messaging application ID

Sending messages

At this point you should have completed the following:

• Downloaded Postman and filled out the Postman Collection form with your individual credentials, and potentially created a Sub-Account and Location in this step.
• Created an Application.
• Ordered number(s).

Let’s head over to Postman and see what it looks like to actually send a message:

1. Open Postman and select Collections.
2. Use the dropdown to open the Bandwidth Messaging Collection and click Send Text Messages.
3. Select POST Send Text Message and then click into the Authorization tab.
   • The Authorization will be pulled from your environment variables as added earlier in the guide.
   • Your Account ID and messaging Application ID will also be filled from the environment variables.
   • The value should read as inherit auth from parent

Now let’s move over to the Body tab in Postman.

1. Enter the following information:
   • From: The number we ordered in the previous section of the guide
   • To: The number you’re sending the message to
   • Text: Update with the message you want to send
   • ApplicationID: From your Application in the Dashboard (autofilled from environment variables)

        

2. Click Send.
3. You should see a Status of 202 Accepted and a message completed to the receiving party.

Message parameters

Parameter	Mandatory	Description
from	Yes	One of your telephone numbers the message should come from (must be in E.164 format, like +19195551212).
to	Yes	The phone number the message should be sent to (must be in E.164 format, like +19195551212).
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.

Related links

• How to Download Message Detail Records (MDRs)
• Message Detail Record (MDR) Field Descriptions