Quick Start Guide

This is a brief walkthrough for setting up and using a Bandwidth messaging application. This guide will outline sending a message, receiving a message, and receiving status callbacks.

Assumptions

• You have already created and set up your Bandwidth Dashboard account.
  • If you have not already done so, please look here for our Account Setup guide.
• You have created a messaging application in the Dashboard UI or using the Dashboard API.
  • Instructions for doing so can be found here.

With an account and application created, we can get started using the Messaging API.

Configuring Callback URLs

Bandwidth will send two different types of Webhooks to a URL specified for the messaging application. Both the Dashboard UI and the API allow for the setting of inbound and outbound callback URLs. When sending a message from a Bandwidth number, our API will send a webhook to the OutboundCallbackURL giving status updates. When a Bandwidth number receives a message, our API will send a webhook to the InboundCallbackURL notifying you of a received message.

The two easiest methods for handling these webhooks personally are creating a server to handle them, or using Pipedream to avoid creating your own server. You may choose to create separate endpoints for inbound and outbound callbacks, or you can handle both types of callbacks in the same endpoint. The latter is not recommended—especially for use cases that are more complex.

Creating a Personal Server

Many of the Bandwidth Samples include code for setting up a local server. When using a locally hosted server, you will not have a valid callback URL, an easy fix for this is hosting your local server somewhere online. A useful tool for hosting local sites on web accessible links is ngrok. Your ngrok link can be used as the domain for your callback URLs.

Using Pipedream

Pipedream is a serverless platform for connecting APIs. Pipedream already has integration for the Bandwidth API. All of the connected tools may be found here. With a Pipedream source or workflow set up, the assigned Pipedream endpoints can be set as your respective callback URLs.

Sending a Message

Sending a text message is one of the simplest ways to interact with the Bandwidth Messaging API. In order to send a text from a Bandwidth phone number, you will need to make a POST request to our API v2 /messages endpoint. This can be done using any of our Sample Apps, SDKs, Postman, or in a program you create. Postman is a useful tool for making HTTP requests without needing to write any code.

More information about sending messages can be found on our Send Messages Guide.

Sent Message Callbacks

After sending a message from a Bandwidth number, our API will send status callbacks to your configured OutboundCallbackURL. You can configure the types of status updates you receive in the Dashboard UI and via the Dashboard API. These status callbacks can be handled in your local server, or with Pipedream. More information about the status callbacks can be found on the Messaging Webhooks page.

Receiving a Message

Bandwidth phone numbers can always receive messages, assuming SMS is enabled for that number in the Dashboard. When a Bandwidth number receives an SMS or MMS message, a message-received webhook is sent to your InboundCallbackURL. This webhook may be handled by your local server, or with Pipedream; so what you chose to do based on this webhook is up to you. Examples for Inbound webhooks may be found on the Messaging Webhooks page.