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?
- An SMS is sent from your system via the 46elks API.
- The 46elks system receives your request and replies with a status of "created".
- When the status of the SMS changes, the 46elks system sends another request to your system with the data about the new delivery status.
- 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:
npm initto initialize a new node application.
npm install expressto install express framework.
Create a file called
app.jsand add the following code:
.\ngrok http 5000command from the folder where ngrok is installed, keep the terminal running.
node .\app.jsinside 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
If you are developing on a local machine with ngrok, you can replace
https://yourapp.io with your ngrok generated URL (e.g.
https://f406-89-164-141-151.ngrok.io) in the
Please note that if you are using ngrok, you'll need to update the URL in
whendelivered every time your ngrok link changes.
Let's register route in our node application:
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
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.
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:
whendeliveredparameter, 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.
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;
The result of the above request is exactly as if you were to to send an request to
https://yourapp.io, with the header
Authorization: Basic <credentials>.
<credentials> is a Base64 string made of username and password separated with a colon, e.g
The base64 string could look something like this;
Let's implement a basic authentication in our application:
First step is to define our API credentials (username and password) in the
whendeliveredparameter while sending the SMS:
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.
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.
npm install jsonwebtokento install jsonwebtoken Node.js package
Require jsonwebtoken library in your code
JWT Secretto 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.
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:
Now it's time to create the JWT token itself. We do this by using our secret key to sign (encrypt) the JWT string:
whendeliveredparameter, you'll add your JWT token like so:
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.