Tomomi Imura

Vonage Team Member

Open web & technology ? HTML5, JavaScript, Node.js. Cat hacks ?, and Internet of Blings ✨ (that slightly more than LED blinks ?). Former Developer Advocate at Vonage, San Francisco.

[Read more]
< Tutorial />

How to Handle Inbound Phone Calls with Node.js

Last updated on May 17, 2021

This is the second 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.

In Part 1 of this tutorial, I showed how to create and secure an application and learned how to make an outbound text-to-voice call using the Voice API with the Node.js client library. In this tutorial, you will learn how to receive inbound calls by implementing a webhook.

View the source code on GitHub.

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.

Screenshot of new Meetings API session in progress
Start developing in minutes with free credits on us. No credit card required!

Using Nexmo Application

In this tutorial, you will use the same application that was created in the previous tutorial to receive a voice call. You also will update the application with webhook endpoint URLs. If you haven’t reviewed the first tutorial, "How to Make an Outbound Text-to-Speech Call with Node.js", refer to the section, Creating a Nexmo Application and Generating a Private Key to create an application.

When a user calls the Nexmo virtual phone number associated with your voice application, Nexmo retrieves the Nexmo Call Control Objects (NCCO) from your answer_url webhook endpoint, and answers the call with a synthesized voice that reads the text you have specified in the NCCO.

Accepting incoming calls
Accepting incoming calls

Diagram 1: Using The Voice API to receive a call to your Nexmo virtual number

Nexmo also sends status information to another webhook endpoint defined by event_url. The event is triggered when the user’s handset is ringing (ringing), when the call is answered (answered), etc. You can find all the events in the API Reference documentation.

Defining Webhook Endpoints

In order to accept an incoming call to your Nexmo virtual phone number, you need to associate your voice application with webhook endpoint URLs.

Just as a previous tutorial showed how to use ngrok to receive SMS messages, let’s use ngrok to expose your webhook endpoint on your local machine as a public URL.

Run ngrok with a port number of your choice (let’s make it 4001 for now):

$ ngrok http 4001

Your local server (localhost:4001) now has a forwarding URL, something like that can be used as your webhook endpoint during development.

Writing WebHook Endpoints with Express

Let's handle the POST requests with Express. You will also need to install body-parser.

$ npm install express body-parser --save

Create a .js file, instantiate express, and listen to the server to port 4001. Because you have set your ngrok to expose localhost:4001, you must stick with the same port.

'use strict'
const app = require('express')();
const bodyParser = require('body-parser');
app.use(bodyParser.urlencoded({ extended: true }));
const server = app.listen(process.env.PORT || 4001, () => {
console.log('Express server listening on port %d in %s mode', server.address().port, app.settings.env);

Let’s define the endpoint for the Answer URL as /answer and the Event URL as /event.

Create an HTTP GET route to handle the requests for /answer to retrieve your NCCO:

app.get('/answer', function (req, res) {
const ncco = [
action: 'talk',
voiceName: 'Jennifer',
text: 'Hello, thank you for calling. This is Jennifer from Nexmo. Ciao.'

Define your text to be read by a synthesized voice in JSON (or JavaScript object, in this case). You can customize the audio with optional params, such as voiceName, which you can choose from varieties of voices for a language, gender, and accent.

The endpoint for the event_url needs to be POST, so let’s define /event:'/event', function (req, res) {

You don’t need to actually return anything if you just want to monitor the status in a terminal.

Updating Nexmo Application with WebHook URLs

Nexmo applications contain configuration information you need to connect to the Voice API endpoints. Previously, we used placeholders for both the Answer URL and the Event URL. Now you are going to use the Nexmo CLI to update the application information with the webhook endpoints you just defined.

You need the Application ID to update the information. You can get it from the make-call.js in the previous tutorial, or use the app:list command:

$ nexmo app:list

The CLI should return a list of each app ID and an app name. Now, use the correct app ID to update the application with the webhook URLs:

$ nexmo app:update c6b78717-db0c-4b8b-9723-ee91400137cf "My Voice App"

Associating the Info with Your Virtual Number

Finally, you need to associate your application with the virtual number you rent from Nexmo. Let’s use the Nexmo CLI again. Use the command nexmo link:app followed by the phone number, which must start with a country code and then the app ID. So, the command should look like this:

$ nexmo link:app 12015556649 c6b78717-db0c-4b8b-9723-ee91400137cf

When the linking is successful, the CLI returns with the message, "Number updated".

Testing Your Voice Application

Let's make a phone call to see if your application works! Call your virtual number from your physical phone. If everything works, you should hear the message you have defined in your NCCO.

Also, see your terminal to check the status of your call.

In the next tutorial, you will learn how to record calls as audio files, so stay tuned!

Learn More

Here are some resources you can use to dive deeper into Nexmo APIs and Node.js.

API References and Tools

Nexmo Getting Started Guide for Node.js