How to Receive SMS Messages with Node-RED
Tags: node, sms, tutorial, nodered
Published: 2019-04-24 22:43:02

---
title: How to Receive SMS Messages with Node-RED
published: true
tags: node,SMS,Tutorial,node-red
canonical_url: https://www.nexmo.com/blog/2019/04/24/receive-sms-messages-node-red-dr/
cover_image: https://www.nexmo.com/wp-content/uploads/2019/04/receive-sms-node-red.png
series: "Getting Started with Nexmo and Node-RED"
---

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

In the [previous article](https://dev.to/nexmo/how-to-send-sms-messages-with-node-red-2l2o), 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.

## Prerequisites

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

- [Node.js](https://nodejs.org/en/) and [Node-RED](https://nodered.org/docs/getting-started/installation) installed on your machine
- A Nexmo account—[create one for free](https://dashboard.nexmo.com/sign-up) if you haven’t already
- Optional: [ngrok](https://ngrok.com/download)—get up to speed with [Aaron’s blog post](https://www.nexmo.com/blog/2017/07/04/local-development-nexmo-ngrok-tunnel-dr/)

For this tutorial, you’ll also need a [Nexmo number](https://dashboard.nexmo.com/your-numbers)—and you can purchase one under Numbers > [Buy numbers](https://dashboard.nexmo.com/buy-numbers).

![](https://www.nexmo.com/wp-content/uploads/2019/04/buy-number-nexmo-dashboard.gif)

## 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.

![](https://www.nexmo.com/wp-content/uploads/2019/04/inbound-sms-flow-get.gif)

## 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](https://ngrok.com).

[Download](https://ngrok.com/download) and install **ngrok** , then run it in the terminal to start a tunnel on port `1880`.

```
$ ./ngrok http 1880
```

![](https://www.nexmo.com/wp-content/uploads/2019/04/ngrok-send-sms-nodered.png)

## 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](https://dashboard.nexmo.com/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`.

![](https://www.nexmo.com/wp-content/uploads/2019/04/inbound-sms-webhook-for-number-1.png)

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

![](https://www.nexmo.com/wp-content/uploads/2019/04/received-sms-in-debug-1.png)

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](https://developer.nexmo.com/api/sms#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?

## Resources

- [How to Send SMS Messages with Node-RED](https://dev.to/nexmo/how-to-send-sms-messages-with-node-red-2l2o)
- [Announcing the Nexmo Node-RED Package](https://www.nexmo.com/blog/2019/02/21/nexmo-node-red-package-dr/)
- [API Reference for Inbound SMS](https://developer.nexmo.com/api/sms#inbound-sms)
- Learn more about the Nexmo [SMS API](https://developer.nexmo.com/api/sms)
- Have a closer look at [Node-RED](https://nodered.org/docs/)