How to receive SMS with Node.js

Getting started

In order to receive an SMS, you need the following:

• A 46elks account.
• A virtual phone number with SMS capabilities.
• A server connected to the internet.
  • For development purposes you can use ngrok.

How does it work to receive an SMS

A simplified process of what's happening when receiving an SMS looks like this:

1. Someone sends an SMS to your virtual phone number.
2. The 46elks API receives the incoming SMS and returns data about it to your system.
3. Your system then reads the data and performs corresponding actions.

Configuring the sms_url

When you want to receive SMS on you virtual number you must first inform the 46elks API by configuring a parameter we call sms_url. This is a set of instructions to the API on what to do upon incoming SMS.

Please follow our guide on how to configure sms_url on your virtual phone number. When you're done, come back here.

For the purposes of this guide, let's assume the following:

• Your domain is https://yourapp.io.
• Your webhook route is /incoming-sms.
• You have set https://yourapp.io/incoming-sms as the sms_url on your virtual phone number.

Next we are going to create the listening script (the webhook) for incoming SMS.

Create a webhook for incoming SMS

We are going to create simple express.js application using ngrok to make our local server accessible publicly. If you haven't setup ngrok already, please follow or ngrok guide and come back here afterwards.

Let's setup our local server:

1. Run npm init in your project folder to initialize node application.

2. Run npm install express to install the express framework.

3. Create a file called app.js and add the following code to it:

4. Run .\ngrok http 5000 command from the folder where ngrok is installed, keep the terminal running.

5. Run node .\app.js inside project directory to start the server.

Now that our server is up and running, let's build our application:

1. Your webhook expects a http POST request. Let’s register a corresponding route in our application. The route specified in this example is /incoming-sms.

2. We need to parse the body of the incoming POST request, since the data is encoded as x-www-form-urlencoded. The parsing is done with the following code:

3. As stated in the documentation for receiving SMS, your webhook must respond with a HTTP status in the range 200-204. If not, the 46elks API will consider the request failed and keep trying to send it. To respond with a 200 status, add the following line:

That is all the basic info you need to set up a webhook to receive incoming SMS. Below is the full code of what we have done so far:

Bonus Step - Phone number parsing and validation

Parsing and validating a phone number can be a tedious task. Fortunately there are libraries to help you out. In this example we are going to use Google's libphonenumber. Go ahead and install the library with npm install google-libphonenumber.

Parse and validate a phone number

1. Require PhoneNumberUtil instance

2. Parse the string representing a phone number

3. Remember to wrap your parsing in the try catch block, as trying to parse the string of invalid format will throw an error.

4. Ensure that you validate the phone number as well. Even if string could be parsed as phone number it is not guaranteed to be a valid phone number.

Format phone number to E.164

Now that we have parsed the number and ensured it's a valid number, we also want to check if the phone number is formatted accordingly to the E.164 format.

1. Require the phone number format instance.

2. Format a phone number object.

Now you'll have a fully validated and correctly formatted phone number. The full code example for receiving incoming SMS and validating the phone number is show below:

Do you want help?

Please contact our support. We love talking to our users.