How to receive SMS Delivery Reports (DLRs) with Node.js

What is SMS Delivery Report (DLR)?

SMS Delivery report shows the current status of the SMS you have tried to send. The status will be set to either ”delivered” or ”failed”.

How does it work?

1. An SMS is sent from your system via the 46elks API.
2. The 46elks system receives your request and replies with a status of "created".
3. When the status of the SMS changes, the 46elks system sends another request to your system with the data about the new delivery status.
4. Your system receives the DLR and depending on the status your system can perform correspending actions.

Point the 46elks API to where the DLR should be sent

To receive DLRs, your system has to specify an entry point to where the DLRs will be sent. That entry point is simply an URL that your system listens to, often called a webhook.

You specify the URL in a parameter called whendelivered when you are making a request to send an SMS. We have a full guide on how to send SMS with Node and in short it looks like this:

Notice line 5 in the above example. That's the "magic" to activate the DLRs.

The DLR is sent as a http POST request to the specified URL in whendeliviered. More info about this is available in DLR Docs.

Set up a local server

Before we create our webhook we'll need a server.

We are going to create simple express.js application using ngrok to make our local server accessible publicly. If you haven't used ngrok before, please follow or ngrok guide and come back here afterwards. Then do the following:

1. Run npm init to initialize a new node application.

2. Run npm install express to install express framework.

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

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

Implement the DLR webhook

For the purposes of this guide, let's assume your domain is https://yourapp.io and the web hook route is /elks/dlrs.

Let's register route in our node application:

1. DLR is a http POST request that will be sent to your webhook. We need to set up a rout for that in our Node application. The route specified in this example is /elks/dlrs

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:

   Now your system is able to extract the request data. In the above example we have extracted the following:

   • id - The unique id of the related message in the 46elks systems.
   • status - Delivery status of either ”delivered” or ”failed”.
   • delivered - The delivery time in UTC. Only included if the message is delivered.

3. As stated in the documentation, 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 information you need to set up and use basic DLRs.

How to implement DLR webhook with Authentication

Using authentication in a production environment is strongly recommended as your webhook will be publicly accessible. By using authentication you can make sure that the incoming request is sent by 46elks API and not by someone else.

There are two ways of achieving authentication:

• Basic Authentication
• URL Query Parameters Authentication

For both ways the same principle applies:

• In whendelivered parameter, you specify your DLRs webhook URL.
• It is possible to specify additional parameters that will be expected in DLRs webhook.
• Request parameters are validated in the webhook, if parameters are valid, the request is considered authentic.

Basic Authentication

A basic authentication is a simple way to identify yourself by providing a username and a password while making a request. The request could look something like this; https://john_doe:my_password@yourapp.io.

Let's implement a basic authentication in our application:

1. First step is to define our API credentials (username and password) in the whendelivered parameter while sending the SMS:

2. Next step is to validate the credentials in our DLRs webhook:

Now you are validating the request using Basic Authentication, making sure it is a legit 46elks request before handling its data.

Here's a full code reference for our DLRs webhook with basic authentication:

URL Query Parameters Authentication using JWT

The second authentication method is URL query parameters authentication. It uses the same principle as basic authentication but with the possibility of sending any number of parameters and their respective values, e.g. https://john_doe:my_password@yourapp.io/elks/dlrs?param1=value1&param2=value2.

JWT (JSON Web Token) is an open, industry standard (RFC 7519) method for representing claims securely between two parties. In other words, JWT is simply a JSON payload containing a particular claim. The key property of JWTs is that in order to confirm if they are valid we only need to look at the token itself.

Using URL query parameters along with JWT or similar technology is a more secure way of authenticating than basic authentication as your system can control encryption and decryption of data while being able to send more than one parameter-value pair.

Let's implement this in our application.

1. Run npm install jsonwebtoken to install jsonwebtoken Node.js package

2. Require jsonwebtoken library in your code

3. Set JWT Secret to a random string. This is the key we'll use to encrypt and decrypt our JWT.

   Please note that you should never expose your JWT secret in your code while developing a real application that will be used in a production environment. In that scenario you should use environment variables instead. For the purposes of this guide however, the key will be a string set in a simple variable.

4. In this guide we have no need to use the JWT payload data, but if your project requires it this is how you should declare it:

5. Now it's time to create the JWT token itself. We do this by using our secret key to sign (encrypt) the JWT string:

6. In your whendelivered parameter, you'll add your JWT token like so:

7. Next step is to verify the JWT token in our DLRs webhook:

Here's a full code reference for our DLRs webhook with JWT authentication

Do you want help?

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