In Context

The next-generation communications blog from Nexmo

< Back

How to Make an Outbound Text-to-Speech Phone Call with Node.js

January 12, 2017 Published by

This is the first of a two-part Voice API tutorial on making and receiving phone calls with Node.js. It continues the “Getting Started with Nexmo and Node.js” series, which followed our Getting Started series on SMS APIs. See links to prior tutorials in these series at the bottom of the post.

The Nexmo Voice API allows you to build high-quality programmable voice applications in The Cloud. With the Voice API, you can manage outbound and inbound calls in JSON, record and store calls, create a conference call, send text-to-speech messages in 23 languages with varieties of voices and accents, and so on.

In this tutorial, you will learn how to use the Application and Voice APIs to create a text-to-speech outbound phone call securely.

GitHub icon View the source code on GitHub

Securing Your Nexmo Application

Some of Nexmo’s APIs use Nexmo Applications, which contain the security and configuration information you need to connect to the Voice API endpoints.

An Application:

Nexmo voice API make call diagram
Diagram: Using The Voice API to call your mobile phone

Creating a Nexmo Application and Generating a Private Key

Your app needs to authenticate requests to the Voice API. Now, you will generate a private key with The Application API, which allows you to create JSON Web Tokens (JWT) to make the requests.

Let’s create an application with the Nexmo command-line interface (CLI) tool, which will set up the app and generate a private key for you.

First, make sure Node.js 4.0 or above is installed on your machine, then install nexmo-cli from npm:

Then set up the CLI with your Nexmo API key and secret:

This will save your credentials to ~/.nexmorc.

Once configured, you are going to create an application in your working directory using the CLI.

Along with the app:create command, you need to register an application name (let’s call it “My Voice App”) as well as two webhook endpoints. You don’t need to specify the answer and event URLs for making calls, so use some placeholder values for now and leave the optional field blank:

When the application is successfully created, the CLI returns something like this:

These are your application ID and private key (in this case, the private.key file is generated in the same directory). You will need both the App ID and the private key to make a phone call using the Voice API.

You can edit the app info with the nexmo app:update command later as you need. To learn more about the CLI, read the doc on the GitHub repo.

Making a Call with Nexmo Voice API

Now you are going to use the Voice API to make a call with the Nexmo Node.js client library. If you have not followed the Getting Started with SMS using Node.js guide, first make sure Node.js is installed on your machine and install the Nexmo Node.js library via npm:

Create a .js file, and initialize Nexmo with your API credentials, as well as the Application ID and the private key you just created. The value for the privateKey has to be read from the saved file, not the path of the file:

Then, make a call with the calls.create function:

Let’s take a phone number to call as a command line argument. So when you run this code, run it with a number. The FROM_NUMBER should be your virtual number, which you can find in your dashboard.

The synthesized voice will read the text from your webhook endpoint at answer_url, which contains NCCO in JSON. You can use the example hosted on Nexmo’s Community GitHub repo, or create your own and host it on a server (or even on GitHub Gist) that the Nexmo API can reach.

my-greeting.json:

You can customize the audio with optional params such as voiceName. You can choose from varieties of voices by language, gender and accent.

Or you can use an audio file:

my-greeting-audio.json:

Now, let’s run the app to call to your phone. Use the phone number starting with a country code (“1” for the US, for example) as an argument when running the node code:

When it is successful, it retrieves the NCCO from your webhook, executes the actions, and terminates the call. You may observe some latency depending on the phone carrier. It can take some time for your phone to ring after the code is executed.

In this exercise, the phone number is taken from a command line but, of course, you can take the request from web via POST. Refer to Getting Started with SMS with Node.js for a simple example with Express.js.

Part 2 of this tutorial will show you how to handle incoming calls using Node.js and the Nexmo Voice API.

Learn More

API References and Tools

Nexmo Getting Started Guide for Node.js

Nexmo Logo

Tags: , , , , , ,

Categorised in: , , ,

This post was written by