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 Vonage API 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!
Before getting started, you’ll need a few things:
- Node.js and Node-RED installed on your machine
- Optional: ngrok—get up to speed with Aaron’s blog post
Vonage API Account
To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.
This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs. If you’ve just signed up, the initial cost of a number will be easily covered by your available credit.
Defining a Webhook Endpoint
In order to receive SMS messages using the Vonage API, you need to associate a webhook endpoint with a virtual number that you have rented from Vonage. 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.
http input node, select
GET as a
Method and fill in the
URL field with something like
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 Vonage 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
$ ./ngrok http 1880
Setting Up the Endpoint
The last step is letting the Vonage 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
Now, if you send a text message to your virtual 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:
||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.|
||Your Nexmo number that the SMS was sent to, in E.164 format.|
||The content of the received SMS message.|
||The type of the message body received (
||The first word in the message body. This is typically used with short codes.|
||The time when Nexmo started to push this Delivery Receipt to your webhook endpoint.|
Find out more about these parameters in the Vonage API Reference for Inbound SMS.
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?
- How to Send SMS Messages with Node-RED
- Announcing the Nexmo Node-RED Package
- API Reference for Inbound SMS
- Learn more about the Vonage SMS API
- Have a closer look at Node-RED
Try Another Tutorial
- Send Group Notifications with Google Sheets and Node-RED
- How to Build an IVR using Node-RED and the Nexmo APIs
- Build Your Own Voicemail With Node-RED and the Nexmo Voice API
- Forward a Call via a Voice Proxy with Node-RED
- Build a Conference Call with Node-RED
- Verify Phone Numbers with Node-RED
- How to Stream Audio into a Call with Node-RED
- How to Make Text-to-Speech Phone Calls with Node-RED
- How to Receive Phone Calls with Node-RED