Node.js Messaging Quickstart

Build a simple Node.js application that receives an SMS message and sends a reply.

👍

You're ready for this Quickstart if you've got the following:

A free trial account
A registered application
A configured FreeClimb Number
Your tools and language installed
Trial accounts: A Verified Number

Clone your sample app

To help you get started we've put together a library of sample applications. For this Quickstart, clone the repository for Node Receive Message Tutorial using Github's interface or git in the command line.

git clone https://github.com/FreeClimbAPI/Node-Receive-Message-Tutorial.git

You can access the full sample app library through your Dashboard or the FreeClimbAPI Github repositories.

Add your keys to your project

Now that you've cloned the repo for your sample app, the next step is to add your API keys so you can authenticate with FreeClimb. To do this, first copy your account ID and authentication token from your Dashboard homepage.

Your API Keys can be copied from your Dashboard homepage.

Create a .env file in the root directory of your repo. Make sure to add the file to your .gitignore file. Add your account ID and authentication token to your .env file, and save the file. Your .env file should look something like this:

ACCOUNT_ID=YOUR-ACCOUNT-TOKEN
AUTH_TOKEN=YOUR-AUTH-TOKEN

The sample app uses Dotenv to read in your keys, and anything else you save, as environment variables.

Replace the placeholder values

In your receiveMessage.js file replace the placeholder values for the To and From numbers. The To number should be a Verified Number and the From number should be your configured FreeClimb Number. Both should be in E.164 format.

When you're done your file should look something like this:

app.post('/incomingSms', (req, res) => {
  let to = '+15555550010' //your Verified Number
  let from = '+15555551101' //your FreeClimb Number
  freeclimb.api.messages.create(from, to, 'Hey! It is your application!').catch(err => {console.log(err)})
})

Make your local server publicly accessible

The fastest way to start testing your FreeClimb application is to temporarily make your local server publicly accessible through a tunneling service. We'll use Ngrok to do this. Start by downloading Ngrok. Unzip the file to install, then open your terminal and navigate to the directory where you've unzipped Ngrok. Use the following command to start a HTTP tunnel on port 80.

./ngrok http 80

Once you run Ngrok you should receive a response with a public URL, that looks something like this:

ngrok by @inconshreveable

Tunnel Status                 online
Version                       2.0/2.0
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://92832de0.ngrok.io -> localhost:80
Forwarding                    https://92832de0.ngrok.io -> localhost:80

Connnections                  ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

The Forwarding URLs point to your local server. Save the URLs and go on to the next step.

Configure your Application's endpoints

Now that you've got a public URL you're ready to configure your application's endpoints. We'll be configuring the smsUrl using your Ngrok URL and the route reference /incomingSms.

Go to the Apps page in your Dashboard. You should see your registered FreeClimb app.

Your Apps page with your registered app

Open its App Config, and you'll see its application ID, alias, and some options for URL configuration. Enter your Ngrok URL into the smsUrl field, and add the route /incomingSms at the end of the URL.

https://YOUR-URL.ngrok.io/incomingSms

When you're done the App Config should look something like this:

Example of a completed app config

Save your updated App Config.

Experience your app

Once you've updated your App Config you're all ready to run your app! Run the application with the command:

node receiveMessage.js

Once the app is running, use your Verified Number to send a message to your configured FreeClimb Number. If everything is set up right you should receive the message, "Hey! It's your application!"

Congratulations! You've just made your first messaging application!

Next steps

For a more detailed explanation of the code used, see How to Reply to an Incoming Message.

Updated 4 months ago

Node.js Messaging Quickstart


Build a simple Node.js application that receives an SMS message and sends a reply.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.