Node.JS Voice QuickStart Tutorial

In this Voice Quickstart Tutorial, we'll walk you through building a basic sample application in Node.JS that responds to inbound calls and plays a message to the caller. In other words, we're creating the "Hello, World" of IVR applications. We'll go through the following steps:

1. Sign up for a free trial account with FreeClimb
2. Create an application in your account
3. Configure a FreeClimb number to accept a call
4. Ensure your development machine is ready
5. Install the FreeClimb Node.JS SDK
6. Write the Node.JS code to play a message
7. Expose your local web server to the internet with ngrok
8. Connect your application's URL to FreeClimb
9. Test your application by making a call

This whole process should take less than 30 minutes, and our support team will be happy to help if you run into any challenges. Let’s go!

Sign up for a FreeClimb account to get started

Go to the FreeClimb account creation page to sign up for an account. You can also sign up using your existing GitHub account credentials.

When you sign up, you'll be prompted to add a verified number. While you're using your free trial account, you'll only be able to make outbound calls to numbers you add as verified numbers. Enter the phone number (US only) of a device you'll be able to access easily while you're working with FreeClimb. You’ll receive a confirmation code by SMS to your device. Enter it in the dashboard, and you'll be ready to move on to the next step.

Create an application in your account

Once you're logged in, you'll be directed to your FreeClimb dashboard. From your dashboard, you can manage your account, add applications, configure phone settings, and review logs. First, we’re going to look at the Applications panel, which you can find in the left sidebar.

FreeClimb applications are the interface between your code and the FreeClimb backend, which handles the transmission of data between the internet and telephone networks. FreeClimb will connect your App ID to a FreeClimb telephone number, so that it can correctly direct incoming and outgoing voice data.

You'll see a list of existing FreeClimb apps in your Applications panel. New trial accounts come with a pre-configured app called "My FreeClimb Application" - use this application or create a new one by clicking on Register New App and entering an alias for it. Each application will have a unique App ID. Keep your App ID handy, either in your browser or on your clipboard. For now, you don't need to enter any URLs into the configuration.

Configure a FreeClimb number to accept a call

FreeClimb numbers are regular phone numbers that you can dial from any mobile or landline phone. When a call is received, FreeClimb picks it up for you and forwards it to an application.

In your FreeClimb dashboard, click on Manage Numbers in the left sidebar to see a list of the numbers you have in your account. You also see their associations with applications. New trial accounts already come with a phone number. You can use that number for the tutorial. If the number is not assigned to the correct application, click the View button next to it, change the "App" drop-down and click Update to confirm.

After completing this tutorial, you can choose a different number when you upgrade your account. For testing purposes, we’ll use the randomly assigned number and your verified outbound number.

First, let’s make sure you’re ready to use Node.JS from your development environment.

Ensure your development machine is ready

Double-check that your machine has the following prerequisites installed:

• Node.JS
• A package manager: npm, Yarn

Clone our Node.JS repo for the fastest setup

The repository for this tutorial is available on Github.

Clone and install dependencies.

Clone the repository to your local environment.
git clone https://github.com/FreeClimbAPI/Node-Getting-Started-Tutorial.git
Navigate to the project directory in your terminal.
Install the project dependencies by running npm install or yarn install

Set up Environment Variables

We’ll use the dotenv package to handle environment variables in this tutorial. To set up your environment variables, navigate to the project directory and create a file named .env. In this file, add your account ID and API key. It should look like this:

ACCOUNT_ID=//add your account ID here
API_KEY=//add your API key here

Make sure to save the file after you’re done editing.

Create a PerCL Script in Node.JS to connect to your application

The FreeClimb SDK includes support for Performance Command Language, or PerCL scripts. The client-side application in a FreeClimb application is the FreeClimb platform, which handles a different data format than a typical web application. PerCL is a scripting language that converts between JSON-formatted data and audio recordings and gives the commands to transmit that data back and forth between web applications and the telephone network.

In this tutorial, PerCL is used to turn a text string into an audio message that we then play for the caller. The SDK enables you to write that PerCL script directly in Node.JS.

The business logic of the sample application is contained entirely in gettingStarted.js. We have only a single route for now, since all this application will do is answer incoming calls with a static message:

• The script initializes the FreeClimb SDK with your account ID and API key that you set up in your .env file.
• There is a single route for a POST method called “/incomingCall” which holds all the logic for our sample app.
• We start by using the FreeClimb SDK to create a Say script in PerCL. The Say script only needs a text string as a parameter, which will be read to the caller.
• If the endpoint is successfully accessed, we use the SDK to start the PerCL build. The script then returns a custom success message containing the result of the PerCL build in JSON, and relays our “Hello world!” message to the caller.

require("dotenv").config();
const freeclimbSDK = require('@freeclimb/sdk')
const express = require('express')
const app = express()
const port = process.env.PORT ?? 3000

// your freeclimb API key (available in the Dashboard) - be sure to set up environment variables to store these values
const accountId = process.env.ACCOUNT_ID
const apiKey = process.env.API_KEY
const freeclimbConfig = freeclimbSDK.createConfiguration({
  accountId,
  apiKey,
});
const freeclimb = new freeclimbSDK.DefaultApi(freeclimbConfig);

// Responds to incoming FreeClimb inbound webhook with PerCl
// https://docs.freeclimb.com/reference/inbound
app.post("/incomingCall", (req, res) => {
  // Create Say script to greet caller
  const script = new PerclScript({
    commands: [new Say({ text: "Hello World! " })],
  });

  // Add greeting to PerCL script and append to response
  console.log(`  perCL response is: ${JSON.stringify(script.build())}`);
  res.status(200).json(script.build());
});


app.listen(port)

With our script ready to go, we can start our application by running the node command (make sure to navigate to your project’s directory first):

node gettingStarted.js

Expose your local webserver to the internet with ngrok

The next necessary step in getting your FreeClimb Voice application up and running is to claim a public URL for your application. This is a required step for working with FreeClimb because FreeClimb cannot connect to localhost. We recommend ngrok for a quick, secure way to set up a tunnel from a public URL to your localhost:

• In your terminal, use ngrok to open a tunnel to your localhost:
  ngrok http 3000
• We use 3000 for the port variable default in gettingStarted.js. If you have made any changes to that variable, use the corresponding port value to run this command
• You should see something like this in your terminal if the setup was successful:

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:3000
Forwarding                    https://92832de0.ngrok.io -> localhost:3000

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

• Save the Forwarding URL - you’ll use it in your Application configuration.

Connect your Node.JS project to FreeClimb

Now, you're ready to tell FreeClimb how to find your application so that it can route calls to your URL.

• Open your FreeClimb dashboard and open the Applications page.
• Select the App you set up earlier, and click App Config.
• In the voiceURL field, enter your ngrok Forwarding URL, and add the route “/incomingCall/” at the end. Your URL will be unique and different from the one shown in this example.
• Save your App Config by clicking Update.

You can leave the other fields blank - for this application, all you need is the VoiceURL connected to the “/incomingCall/” route from your gettingStarted.js file.

With that route added, your application is ready for testing!

📘

How FreeClimb answers voice calls

1. An external call comes in to a registered FreeClimb number.
2. FreeClimb knows the Application associated with that number.
3. FreeClimb makes a POST request to the voiceURL in that App’s configuration.
4. The Application responds with a PerCL script to play a message to the caller.
5. FreeClimb processes the PerCL and plays the message to the caller.

Test your application

This straightforward setup is enough to let you call your FreeClimb number and hear your hello message delivered by FreeClimb.

Double-check that the application is running on your localhost, and that ngrok is running as well. Next, you can pick up your phone and use your verified number to call your FreeClimb number. You should hear a brief message - if you didn’t change anything in gettingStarted.js, it’ll say “Hello, world!” and then hang up. That was your “Hello, world!” moment!

If you didn’t hear the message, take a look in your terminal for any output. If you can see the incoming request in your console, that means your application and FreeClimb are communicating. Your application is receiving the POST request but is not responding correctly. The issue may be in gettingStarted.js.

If you do not see the incoming request in your terminal, double-check your configuration on the FreeClimb dashboard. You may want to check:

• You’re calling from a Verified Number
• Your FreeClimb Number is connected to the Application
• The VoiceURL in your App Config is the correct ngrok URL, with the correct route
  Logs for your App

Reach out to our support team if you need additional help in getting your sample application up and running.

Explore the possibilities with FreeClimb

The basics we’ve covered so far will enable you to get started with a wide range of functionality. A few pointers to help you explore from here:

• The message you heard came from the following lines in gettingStarted.js:

const script = new PerclScript({
    commands: [new Say({ text: "Hello World! " })],
  });

  res.status(200).json(script.build());

• Modify the “Hello world!” string and you’ll get a different message. Reading through the PerCL documentation may give you a better sense of the options you have.
• If you’re looking for more options for different types of responses for voice calls, the Accept an Incoming Call tutorial is a good next step.
• FreeClimb meets industry standards for handling sensitive user data, including HIPAA.
• FreeClimb also enables outbound calling, SMS functionality, and conferencing to connect multiple live callers, and we have guides and sample applications covering many use cases.

FreeClimb is highly scalable and reliable, and is built on a proven platform. While setting up a simple voice application is straightforward, it is the first step towards building an application that can reliably handle large volumes of telephone calls and increasingly complex business logic for managing those calls.