How to Connect a Phone Call to Nexmo In-App Voice

Published May 13, 2018 by Alex Lakatos

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 post, we’ll learn how to forward an incoming phone call from a Nexmo phone number to a user by implementing a Webhook and linking that to a Nexmo Voice application.

Before you begin

Before we begin you’ll need a few things:

  • Node.js installed on your machine
  • Create a free Nexmo account – signup
  • Install the Nexmo Beta CLI:

  • Setup the CLI to use your Nexmo API Key and API Secret. You can get these from the setting page in the Nexmo Dashboard:

Forwarding a call to a user

When a user calls a Nexmo virtual phone number associated with a voice application, Nexmo retrieves the Nexmo Call Control Objects (NCCO) from your answer_url Webhook endpoint. We’ll try to answer the call with a synthesized voice that reads some text and then connects the call onwards to a user. We’ll use the NCCO to create the call flow.

Creating a webhook endpoint

I’m a JavaScript person, so I’m going to write the Webhook using Node and ExpressJS. If you prefer a different language, feel free to use something else — there are Nexmo client libraries for JavaScript, Java, Python, PHP, Ruby, and .NET!

We’ll need to install a few things:

Create an index.js file, instantiate express and body-parser, and listen to the server on port 3000.

Let’s add an endpoint for /event that logs all the events coming from the Nexmo Application:

We also need an endpoint for /answer, responding to HTTP GET requests, that is going to deliver the NCCO when the Nexmo Application retrieves the answer_url. We’ll use a talk building block so the call generates text-to-speech letting the user know they’re calling Jamie, followed by a connect block. We’ll need to add a special app type to the endpoint in order to connect the call with an existing user. You can add your own phone number in the from field.

Now let’s run the server:

While you’re developing, you can run the server locally, and use ngrok to make the server publicly available on the internet, so Nexmo can reach it. We have a tutorial on how to do that!

Now we’ll have to connect the Webhook to a Nexmo Application. I’m going to assume you already have one and show you how to update that application to use the Webhook we just created.

Update your existing application with Webhook URLs

You need the Application ID to update the information. You can use the app:list command with the Nexmo CLI:

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:

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:

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


Now that you’ve linked your number to your application, whenever someone calls your Nexmo number they are going to be connected to a user via In-App Voice. If you want to test this out, you can check out the JavaScript guide detailing how you can implement calling using the SDKs.

What’s next?

If you’d like to continue learning how to use the SDK for JavaScript, check out our In-App Messaging quickstarts where we show you how to create a simple conversation, invite & chat with another user and use more event listeners to show chat history and when a user is typing. If you have more questions about using Nexmo In-App Voice we encourage you to join the Nexmo community slack and check out our Slack channel or email us directly at

Leave a Reply

Your email address will not be published.

Get the latest posts from Nexmo’s next-generation communications blog delivered to your inbox.

By signing up to our communications blog, you accept our privacy policy , which sets out how we use your data and the rights you have in respect of your data. You can opt out of receiving our updates by clicking the unsubscribe link in the email or by emailing us at