In Context

The next-generation communications blog from Nexmo

< Back

How to Receive SMS Messages with Node.js and Express

October 27, 2016 Published by

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

In the previous article, you set up your Nexmo account and learned how to send SMS messages with Node.js. In this article, you will learn about receiving an inbound SMS by implementing a webhook endpoint in Node.js using Express.

GitHub icon View the source code on GitHub

Defining a Webhook Endpoint

In order to receive an SMS from Nexmo you need to associate a webhook endpoint (URL) with a virtual number that you have rented from Nexmo. Inbound Messages to that number are then sent to your webhook endpoint.

A diagram showing how a SMS is received from a user

While you are developing the webhook endpoint, it is a pain to keep deploying your work in progress. To make your life easier, let’s use ngrok to expose your webhook endpoint on your local machine as a public URL!

Using ngrok

First, download ngrok from https://ngrok.com. Once installed, run ngrok on terminal:

running ngrok

Your local server (localhost:3000) now has a ngrok URL, https://71f03962.ngrok.io that can be used as your webhook endpoint during development (also, notice the Web Interface URL – I will explain it later!).

Setting the Webhook Endpoint with Nexmo

Sign in to your Nexmo account, and go to Settings. Scroll all way down to API Settings and fill out the Callback URL for Inbound Message with the ngrok URL with a route, let’s call it inbound, enter https://71f03962.ngrok.io/inbound, and let’s set the HTTP Method to POST then save.

setting your webhook endpoint

Now all your incoming messages will go to the webhook (callback) URL, so let’s write some code with Node.js and Express!

Note: Above we’re setting the webhook endpoint for SMS at an account level. But you can also set up unique webhook endpoints for each virtual number.

Writing WebHook Endpoints with Express

Now, handle the POST requests with Express, so you will also need to install body-parser.

Create a .js file, and instantiate express and listen the server to port 3000. Because you have set your ngrok to expose localhost:3000, you must stick with the same port.

Now, create a HTTP POST route to handle the requests:

Then define the handleParams function:

Let’s run the node code, and try sending some messages from your phone to your virtual number!

screenshot of a user sending a sms message from an Android phone

When you are tunneling your local app with ngrok, you can also inspect the request at http://127.0.0.1:4040/ on your browser:

ngrok inspector

Voilà, now you can see your SMS message has been sent, Nexmo has received the message and passed it on to your express application via a webhook!

If you take a look at the code sample in GitHub, you will notice the extra example – a persist data storage (like the HTML5 Local Storage, but for Node) and the incoming data is stored with each key (message ID) and values. That way, you can set up a /inbound/:id route parameter as named URL segment. For instance, when you access http://localhost:3000/inbound/080000001947F7B2, it returns:

In reality, you should set up a real DB, rather than the data storage.

I hope you find this useful. Let me know, I’m @girlie_mac on Twitter.

References


Nexmo Logo

Tags: , , , ,

Categorised in: , , ,

This post was written by