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:
- Someone sends an SMS to your virtual phone number.
- The 46elks API receives the incoming SMS and returns data about it to your system.
- 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
- Your webhook route is
- You have set
sms_urlon your virtual phone number.
If you are developing on a local machine, you can use ngrok. In that case replace
https://yourapp.io with your ngrok generated URL (e.g.
Please note that if you are using ngrok, you'll need to update your
sms_url each time your ngrok link changes.
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:
npm initin your project folder to initialize node application.
npm install expressto install the express framework.
Create a file called
app.jsand add the following code to it:
.\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 application:
Your webhook expects a http POST request. Let’s register a corresponding route in our 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:
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
Require PhoneNumberUtil instance
Parse the string representing a phone number
Remember to wrap your parsing in the try catch block, as trying to parse the string of invalid format will throw an error.
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.
Require the phone number format instance.
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.