Receiving SMS Messages

Learn how to quickly set up a node.js server to receive SMS messages with the Sinch API.

In this guide you will learn how to:

Learn how to:
  1. Sign up for your free Sinch account
  2. Buy a number
  3. Set up your Node.js application
  4. Configure your Callback URL
  5. Test the application

What you need to know before you start

Before you can get started, you need the following already set up:

  • Node.js and a familiarity with how to create a new app.
  • ngrok. You'll use ngrok to open a tunnel to your local server.

Sign up for your free account

Already have an account?

If you already have a free account, skip to the next section

You can sign up for a free Sinch account here.

  • When you sign up, you'll have to verify your email address and phone number. This lets Sinch verify your identity and you'll also be able to use your phone to send and receive test messages.
  • After you've verified your number, you'll be asked some questions in order to get you started in a way that's relevent to you.
  • After you finish setting up your account, you'll have access to your dashboard where you can view all of your projects and applications. You can also access your account ID, set up API tokens, get phone numbers, and more.
  • Once your account is created, you need to add a new REST API in order to send SMS Messages. Click Add New REST API and your new service plan and ID are token will be created. Take note of them, because you'll use them later.

Buy a number

Already have an number?

If you already have sinch number, skip to the next section

You can get numbers that are set up for SMS, Voice, or both. You can buy a number from any country where Sinch has numbers in inventory. Countries with numbers available for purchase are marked with Direct Access. All other countries will require you to submit a request to Sinch for manual handling.

You can search for and purchase virtual numbers by logging in to your dashboard.

  1. Go to Numbers | Get virtual numbers, fill in the required information, and click SEARCH. If you don't want to specify anything about the number, choose your country and click SEARCH. Available numbers to buy are displayed in the list.

  2. When you see a number you want to buy, click GET next to the number to buy it.

  3. You can configure your number with an SMS, Voice or Campaign ID (only for 10DLC numbers) when you activate the number.

    When you get a virtual number, if supporting documentation is needed, you will see a message in an orange box at the bottom of your form. You won't be able to get a virtual number until supporting documentation is submitted. Click here to learn more about supporting documentation.

Set up your Node.js application

We use webhooks to notify your application when someone sends a text to your Sinch number. To handle these, you will learn how to create a webserver and make it reachable on the Internet.

Create a new node app with npm.

npm init

Accept the defaults for the application.

Add the fetch package with npm to generate the necessary dependencies. In this applicaiton we are going to use Express to handle incoming requests.

npm install node-fetch
npm install express

Create your file

Create a new file named index.js in the project and paste the "Receive an SMS message" code into the file.

Receive an SMS message

// Find your Service Plan ID and API Token at dashboard.sinch.com/sms/api/rest
// Find your Sinch numbers at dashboard.sinch.com/numbers/your-numbers/numbers
const servicePlanId = '';
const apiToken = '';
const express = require('express');
const fetch = require('node-fetch');
const app = express();
const port = 3000;
app.use(express.json());

app.post('/', async (req, res) => {
  var requestBody = req.body;
  console.log(requestBody);
  const sendSMS = {
    from: requestBody.to,
    to: [requestBody.from],
    body: 'You sent: ' + requestBody.body,
  };

  let result = await fetch(
    'https://us.sms.api.sinch.com/xms/v1/' + servicePlanId + '/batches',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer ' + apiToken,
      },
      body: JSON.stringify(sendSMS),
    }
  );
  console.log(await result.json());
  res.send('Ok');
});

app.listen(port, () => {
  console.log(`Listening at http://localhost:${port}`);
});

Change the following parameters in the code to your values.

ParameterYour value
SERVICE_PLAN_IDThe service plan ID found on your Sinch dashboard.
TOKENThe API token found on your Sinch dashboard. Click Show to reveal your API token.

Start your web server and set up a tunnel

Start the server by executing the following command:

node index.js

Now you need to open a tunnel to the server you just set up. We are using ngrok for this. if you don't have ngrok installed already you can install it with the following command:

npm install ngrok -g

Open a terminal or command prompt and enter:

ngrok http 3000

Copy the HTTP address that ends with .ngrok.io.

Configure your Callback URL

You need to configure a Callback URL for your Sinch account. Login to your dashboard. Click on the service plan ID link and edit the Callback URL field with the ngrok.io domain URL from the previous step.

Send an SMS message to your sinch number

Now send an SMS message to your Sinch number from your mobile phone and you will get an automatic reply.

Next steps

Receive an SMS message

// Find your Service Plan ID and API Token at dashboard.sinch.com/sms/api/rest
// Find your Sinch numbers at dashboard.sinch.com/numbers/your-numbers/numbers
const servicePlanId = '';
const apiToken = '';
const express = require('express');
const fetch = require('node-fetch');
const app = express();
const port = 3000;
app.use(express.json());

app.post('/', async (req, res) => {
  var requestBody = req.body;
  console.log(requestBody);
  const sendSMS = {
    from: requestBody.to,
    to: [requestBody.from],
    body: 'You sent: ' + requestBody.body,
  };

  let result = await fetch(
    'https://us.sms.api.sinch.com/xms/v1/' + servicePlanId + '/batches',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer ' + apiToken,
      },
      body: JSON.stringify(sendSMS),
    }
  );
  console.log(await result.json());
  res.send('Ok');
});

app.listen(port, () => {
  console.log(`Listening at http://localhost:${port}`);
});