How to Make an Outbound Text-to-Speech Phone Call with Node.js
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 Vonage 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 Vonage 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.
View the source code on GitHub
Securing Your Vonage Application
Some of Vonage’s APIs use Vonage Applications, which contain the security and configuration information you need to connect to the Voice API endpoints.
An Application:
- holds security information - to connect to Vonage endpoints
- contains configuration data for your app and the URLs to your webhook endpoints
- uses Nexmo Call Control Objects (NCCO) to control your calls
Creating a Vonage 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 our 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 Vonage 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 Vonage app:update command later as you need. To learn more about the CLI, read the doc on the GitHub repo.
Making a Call with Vonage Voice API
Now you are going to use the Voice API to make a call with the Vonage 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 Vonage Node.js library via npm:
Create a .js file, and initialize Vonage 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 Vonage’s Community GitHub repo, or create your own and host it on a server (or even on GitHub Gist) that the Vonage 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 Vonage Voice API.