Building an Interactive SMS Delivery Notifications System Using ExpressJS

Published September 29, 2016 by Sidharth Sharma
This is a guest post by Cristiano Betta
Cristiano Betta

One of the amazing things about SMS is how ubiquitous it is. Whether you have a smartphone or an old ’90s “dumb” phone you will be able to send and receive SMS messages. While many companies only use them as a notification service, they become really powerful when they facilitate a two way communication channel between companies and customers.

Notifications for a package delivery company

For this tutorial we’ll create an interactive notifications system for a package delivery company. For this purpose we’ve created a simple “Nexmo Mail” app that allows an employee of the delivery company to type in a phone number and notify the recipient of a package that will be delivered.

Delivery System

This app serves as our starting point for this tutorial. It is a basic Express app, written in Javascript with a few extra modules to make things easier. We’ve added the body-parser module to parse our form submissions, and we added Bootstrap to make our UI look a bit more attractive. Finally, we added some babel modules so that we can write modern ES2015-flavored Javascript.

You can download the starting point of this tutorial from Github:

Then visit localhost:3000 in your browser and submit a phone number in international format, e.g. 447755555555.

All the code for this starting point can be found on the number-form branch on Github. All the code we will be adding below can be found on the delivery-notifications branch. For your convenience, you can see all the changes between our start and end point on Github as well.

The Nexmo SMS API

The Nexmo SMS API provides you with low latency and high deliverability. It is the most reliable way to reach users around the globe. While it has plenty of features we’ll only be looking at two core elements: sending and receiving basic text messages. We will use this API to send people a notification of their delivery, offering them to change their delivery slot, and listen to any changes they send to us. To do this we are going to add the following changes to our app:

  • Add Nexmo to our app
  • Send an SMS message to the number provided with their delivery slot and instructions on how to change their slot
  • Listen to and confirm incoming text messages from the user to change their slot

We will be hardcoding the options in our app just to keep things simple. In your app you will obviously be determining the user’s options based on some amazing machine learning algorithm you’ve personally invented.

Adding Nexmo to our app

In order to send an SMS message via Nexmo we’re going to have to add the nexmo module to the project.

As you can see, we also added the dotenv module. This is just so that the app can load the API credentials from a .env file. You can find your credentials on the settings page of your Nexmo account.

We also added the Nexmo phone number that we will be sending an SMS message from to the .env file. You can buy a number from the Nexmo Dashboard, or you can use the nexmo-cli library and buy one straight from the command line.

For example to buy a UK phone number starting with 077:

Now that we have our API key, secret, and Nexmo phone number, we initialize the Nexmo client.

From now on we can use nexmo anywhere in our app to make the API calls we need.

Sending an SMS message

Delivery System

Currently when the employee submits a phone number it calls the POST /notify endpoint which simply outputs a text confirmation in the browser. We will need to add some code to send an SMS message with the planned delivery slot, and a list of options for them to choose from.

Let’s hardcode some options for the user to change their delivery slot to.

We can use these options to generate a pretty text message to send to the user.

Note: We didn’t hardcode the whole message here as we will need these options again later.

Next up all we need to do is send the message to the phone number that was submitted.

We wrapped the actual Nexmo API call in a send function to make things more readable and reusable. The send function wraps the nexmo.sms.sendTextMessage API and prefills the Nexmo phone number we bought before.

If you now try and resubmit your own mobile number, you should get a text message within seconds.

Incoming Messages

Delivery System

Our final trick is to receive an incoming message from the user replying to our text message sent earlier. To do this, we are going to have to make our app available publicly to a Nexmo webhook.

Let’s start by adding a dummy endpoint for the webhook to call.

You have a few options to make your app publicly reachable by the Nexmo webhooks. If you are lucky enough to have a public IP on your machine, you should be ready to go. For the rest of us, we could either deploy the app, use an SSH tunnel, or my favorite solution: use the amazing ngrok tool.

Once your app is publicly available we can link our number to make a call to this endpoint when a SMS has been received. For this, we use the nexmo-clionce again.

If you get any errors at this state please make sure you are using the Nexmo phone number on your account, and that the URL is publicly accessible.

Our last step is to expand our endpoint to take the incoming message, parse the response, check if it contains one of our options, and send another text message to confirm their selection.

Now try replying to the message you received earlier. It might take a few seconds depending on your internet connection but you should get a confirmation within a few seconds. Also try and reply with some random text messages and see what happens.

Next steps

The Nexmo SMS API has a lot more options than I showed here including Flash Messages, vCard, vCal, and much more. Personally I really like how easy the nexmo-cli make it to buy phone numbers and tie them to an endpoint.

I’d love to know what you’d add next? Please drop me a tweet (I’m @cbetta) with your thoughts and ideas.

Nexmo Logo