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.
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:
- holds security information – to connect to Nexmo endpoints
-
contains configuration data for your app and the URLs to your webhook endpoints
-
uses Nexmo Call Control Objects (NCCO) to control your calls
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:
|
1 2 |
$ npm install nexmo-cli -g |
Then set up the CLI with your Nexmo API key and secret:
|
1 2 |
$ nexmo setup API_KEY API_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:
|
1 2 |
$ nexmo app:create "My Voice App" http://example.com/answer http://example.com/event --keyfile private.key |
When the application is successfully created, the CLI returns something like this:
|
1 2 3 |
Application created: c6b78717-db0c-4b8b-9723-ee91400137cf Private Key saved to: private.key |
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:
|
1 2 |
$ npn install nexmo --save |
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:
|
1 2 3 4 5 6 7 8 |
const privateKey = require('fs').readFileSync(privateKeyFile); const nexmo = new Nexmo({ apiKey: NEXMO_API_KEY, apiSecret: NEXMO_API_SECRET, applicationId: appId, privateKey: privateKey }); |
Then, make a call with the calls.create function:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
nexmo.calls.create({ to: [{ type: 'phone', number: process.argv[2] // take a phone number from command line argument }], from: { type: 'phone', number: FROM_NUMBER // your virtual number }, answer_url: ['https://nexmo-community.github.io/ncco-examples/first_call_talk.json'] }, (err, res) => if(err) { console.error(err); } else { console.log(res); } }); |
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:
|
1 2 3 4 5 6 7 8 |
[ { "action": "talk", "voiceName": "Chipmunk", "text": "Yo, this is Chipmunk. I am created with Nexmo Voice API!" } ] |
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:
|
1 2 3 4 5 6 7 |
[ { "action": "stream", "streamUrl": ["https://example.com/audio_file.mp3"] } ] |
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:
|
1 2 |
$ node voice-call.js 15105551234 |
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
- How to Send SMS Messages with Node.js and Express
- How to Receive SMS Messages with Node.js and Express
- How to Receive an SMS Delivery Receipt from a Mobile Carrier with Node.js
Developer
Business