How to Receive SMS Messages with Node-RED

Published April 24, 2019 by Julia Biro
Categories:

This is the second article in a series of “Getting Started with Nexmo and Node-RED” tutorials.

In the previous article, you set up your Nexmo account and Node-RED editor, learned how to send SMS messages, and learned how to handle delivery receipts. Now it’s time to learn about receiving SMS messages by implementing a webhook endpoint using Node-RED.

Get this flow from the Node-RED Library or follow along!

Prerequisites

Before getting started, you’ll need a few things:

For this tutorial, you’ll also need a Nexmo number—and you can purchase one under Numbers > Buy numbers.

Defining a Webhook Endpoint

In order to receive SMS messages with Nexmo, you need to associate a webhook endpoint with a virtual number that you have rented from Nexmo. Inbound Messages to that number will then be sent to your webhook endpoint.

First, set up this webhook endpoint in your Node-RED editor. Connect a http input node to a http response node, as well as to a debug node, so that you can view your inbound messages in the debug area.
In the http input node, select GET as a Method and fill in the URL field with something like /inbound-sms.
The http response node should have 200 set as Status code, but don’t worry about it, this is the default value.

Exposing Your Local Server to the Internet

Next you’ll have to expose your local server to the internet, so that Nexmo can access it. If you’re running Node-RED on a public webserver instead of your local machine, you can skip this stage.
Otherwise, a convenient way to do this is by using a tunneling service like ngrok.

Download and install ngrok, then run it in the terminal to start a tunnel on port 1880.

Setting Up the Endpoint with Nexmo

The last step is letting the Nexmo SMS API know where it should forward the inbound messages.
Associate a webhook endpoint with one of your virtual numbers by going to Your numbers, then clicking the settings icon next to the number you’d like to configure.
Next, fill in the Inbound Webhook URL field with YOUR_NGROK_URL/inbound-sms and Save changes.

Now, if you send a text message to your Nexmo number, you should see the message object appear in the debug sidebar.

The message payload will contain a couple of key values that should be noted:

KEY DESCRIPTION
msisdn Mobile Station International Subscriber Directory Number (MSISDN) is a number used to identify a mobile phone number internationally. In this case, this will be the sender’s number in E.164 format. For example 447401234567.
to Your Nexmo number that the SMS was sent to, in E.164 format.
text The content of the received SMS message.
type The type of the message body received (text key). Possible values are text, unicode and binary.
keyword The first word in the message body. This is typically used with short codes.
message-timestamp The time when Nexmo started to push this Delivery Receipt to your webhook endpoint.

Find out more about these parameters in the Nexmo API Reference for Inbound SMS.

Next Steps

At this point, we’re only logging the inbound messages in the debug area, but possibilities are endless. Store them in a database, forward, translate, post them—or why not set up an autoresponder?

Ready to take it one step further? Have a look at Sam‘s flow for Receiving Concatenated SMS Messages from Nexmo.

Resources

Leave a Reply

Your email address will not be published.