We've built this tutorial using the Vonage SMS API, Node.js, and Express

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

View the source code on GitHub

Defining a Webhook Endpoint

To receive an SMS message from Vonage, you need to associate a webhook endpoint (URL) with a virtual number you have rented from Vonage. Inbound Messages to that number are then sent to your webhook endpoint.

While 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 an ngrok URL like https://71f03962.ngrok.io that can be used as your webhook endpoint during development. Also, notice the Web Interface URL—you can inspect, modify, and replay your requests here—more about this later!

Setting the Webhook Endpoint With Vonage

Sign in to your Vonage account, go to Settings, and find the SMS Settings section.

Vonage has two different APIs capable of sending and receiving SMS messages. You can only use one at a time because it will change the format of the webhooks you receive. This time, we're going with the SMS API, so make sure this is selected.

Next, fill out the Inbound SMS webhooks field using the ngrok URL with a route—let’s call it "inbound". Enter https://YOUR_NGROK_URL/inbound, set the HTTP Method to POST then click on Save changes.

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. Alternatively, you can also set up unique webhook endpoints for each virtual number by clicking Manage next to one of your virtual numbers in the Vonage dashboard.

Writing Webhook Endpoints With Express

Next, you'll handle the POST requests with Express, so install it.

Add "type": "module" to your package.json file to enable import statements.

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

import express from 'express';

const { json, urlencoded } = express;

const app = express();

app.use(json());
app.use(
    urlencoded({
        extended: true
    })
);

const PORT = 3000;
app.listen(PORT, () => {
    console.log(`Server listening at http://localhost:${PORT}`);
});

Next, create an HTTP POST route to handle the requests:

app.post('/inbound', (req, res) => {
  handleParams(req.body, res);
});

Then define the handleParams function:

function handleParams(params, res) {
  if (!params.to || !params.msisdn) {
    console.log('This is not a valid inbound SMS message!');
  } else {
    let incomingData = {
      messageId: params.messageId,
      from: params.msisdn,
      text: params.text,
      type: params.type,
      timestamp: params['message-timestamp']
    };
    console.log('Success', incomingData);
  }
  res.status(200).end();
}

Run the node code, and try sending some messages from your phone to your virtual number!

screenshot of a user sending an 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. Vonage has received the message and passed it on to your Express application via a Webhook!

I hope you found this helpful. Let us know @VonageDev on Twitter.

References

• Vonage SMS API

• Ngrok