Receive an incoming SMS Message
Note:
Before you can get started, you need the following already set up:
- Set all SMS API configuration settings.
- 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.
Learn how to handle incoming SMS messages in a Node.js application with the Sinch Node.js SDK.
Set up your Node.js application
First we'll create a Node project using npm. This creates a package.json and the core dependencies necessary to start coding.
To create the project, do the following steps:
- Create a folder called
receive-sms-app
- Navigate into the folder you created and run the following command.
npm init
This command adds the package.json file. You will be prompted to provide values for the fields. For this tutorial, you can simply accept the default values and press enter at each stage.
You can install the Sinch Node.js SDK using either NPM or Yarn:
NPMYarnnpm install @sinch/sdk-core
yarn add @sinch/sdk-core
- Next, install the Fastify package. Fastify is a lightweight webserver that we will use to respond to webhooks.
npm install fastify
Note:
@sinch/sdk-core
and fastify
packages can be imported using import
statements.import { SinchClient } from '@sinch/sdk-core';
import Fastify from 'fastify';
Create your file
Create a new file namedindex.js
in the project and paste the provided "Receive an SMS message" code into the file.Modify your application
The code provided includes placeholder parameters. You'll need to update the parameters detailed in the following subsections with your values.
Initialize the client
Before initializing a client using this SDK, you'll need three pieces of information:
- Your Project ID
- An access key ID
- An access key Secret
Note:
To start using the SDK, you need to initialize the main client class with your credentials from your Sinch dashboard.
const {SinchClient} = require('@sinch/sdk-core');
const sinchClient = new SinchClient({
projectId: "YOUR_project_id",
keyId: "YOUR_access_key",
keySecret: "YOUR_access_secret"
});
Note:
For testing purposes on your local environment it's fine to use hardcoded values, but before deploying to production we strongly recommend using environment variables to store the credentials, as in the following example:
.env
File
PROJECTID="YOUR_project_id"
ACCESSKEY="YOUR_access_key"
ACCESSSECRET="YOUR_access_secret"
app.js
File
const {SinchClient} = require('@sinch/sdk-core');
const sinchClient = new SinchClient({
projectId: process.env.PROJECTID,
keyId: process.env.ACCESSKEY,
keySecret: process.env.ACCESSSECRET
});
Note:
If you are using the Node.js SDK for multiple products that use different sets of authentication credentials, you can include all of the relevant credentials in the same configuration object, as in the following example:
const {SinchClient} = require('@sinch/sdk-core');
const sinchClient = new SinchClient({
projectId: "YOUR_project_id",
keyId: "YOUR_access_key",
keySecret: "YOUR_access_secret",
applicationKey: "YOUR_application_key",
applicationSecret: "YOUR_application_secret"
});
Start your web server and set up a tunnel
- Start the server by executing the following command:
node index.js
- Open a tunnel to the server you just set up. We are using ngrok for this. If you don't have ngrok installed already, install it with the following command:
npm install ngrok -g
- Open a terminal or command prompt and enter:
ngrok http 3000
You will see a screen like the following.
- On the highlighed "Forwarding" line, copy the address ending in
.ngrok.io
.
Configure your Callback URL
- 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 your SMS message
Now send an SMS message to your Sinch number from your mobile phone and you will get an automatic reply.
Next steps
The code you used in theindex.js
file listens for a webhook sent from the Sinch servers and then sends a POST request to the Sinch API /batches
endpoint to send the SMS message.- Explore the API specification to test more endpoints.
Additional resources
- Click here to read more about the batches endpoint.