Messaging Send and Receive

Table of Contents

• Description
• Bandwidth
• Environmental Variables
• Running the Application
• Callback URLs
  • Ngrok

Description

This sample app sends and receives SMS and MMS messages.

Using a tool capable of making POST requests such as Postman, send a POST request to the /messages endpoint with a json body containing the to and text fields. The to field should be an E.164 formatted phone number.

{
  "to": "+19195551234",
  "text": "Hello World!"
}

The example above will text the number +19195551234 the words Hello World!. To send an MMS, add a media field with a list of media URLs:

{
  "to": "+19195551234",
  "text": "Hello World!",
  "media": ["https://cdn2.thecatapi.com/images/MTY3ODIyMQ.jpg"]
}

The other two endpoints are used for handling inbound and outbound webhooks from Bandwidth. In order to use the correct endpoints, you must check the "Use multiple callback URLs" box on the application page in Dashboard. Then in Dashboard, set the INBOUND CALLBACK to /callbacks/inbound/messaging and the STATUS CALLBACK to /callbacks/outbound/messaging/status. The same can be accomplished via the Dashboard API by setting InboundCallbackUrl and OutboundCallbackUrl respectively.

Inbound callbacks are sent notifying you of a received message on a Bandwidth number. This app prints the phone numbers involved and the text received, and saves any media attached to the message to a media folder in the project. Outbound callbacks are status updates for messages sent from a Bandwidth number, this app has a dedicated response for each type of status update.

Bandwidth

In order to use the Bandwidth API users need to set up the appropriate application at the Bandwidth Dashboard and create API tokens.

To create an application log into the Bandwidth Dashboard and navigate to the Applications tab. Fill out the New Application form selecting the service (Messaging or Voice) that the application will be used for. All Bandwidth services require publicly accessible Callback URLs, for more information on how to set one up see Callback URLs.

For more information about API credentials see here

Environmental Variables

The sample app uses the below environmental variables.

BW_ACCOUNT_ID                        # Your Bandwidth Account Id
BW_CLIENT_ID                         # Your Bandwidth API OAuth Client Id
BW_CLIENT_SECRET                     # Your Bandwidth API OAuth Client Secret
BW_NUMBER                            # The Bandwidth phone number involved with this application
BW_MESSAGING_APPLICATION_ID          # Your Messaging Application Id created in the dashboard
LOCAL_PORT                           # The port number you wish to run the sample on

Running the Application

To install the required packages and build the app, run the command:

mvn package

Use the following command to run the application:

mvn spring-boot:run

Callback URLs

For a detailed introduction, check out our Bandwidth Messaging Callbacks page.

Below are the callback paths:

• /callbacks/outbound/messaging/status For Outbound Status Callbacks
• /callbacks/inbound/messaging For Inbound Message Callbacks

Ngrok

A simple way to set up a local callback URL for testing is to use the free tool ngrok.
After you have downloaded and installed ngrok run the following command to open a public tunnel to your port ($LOCAL_PORT)

ngrok http $LOCAL_PORT

You can view your public URL at http://127.0.0.1:4040 after ngrok is running. You can also view the status of the tunnel and requests/responses here. Once your public ngrok url has been created, use it as the base of the callback URLs in the messaging application created in the Bandwidth section.