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.

Nexmo Stitch, a new product currently in Developer Preview, enables communications across multiple channels including in-app messaging and in-app voice.

In this post, we'll learn how to forward an incoming phone call from a Nexmo phone number to a Stitch user by implementing a Webhook and linking that to a Nexmo Voice application.

Before we begin you’ll need a few things:

• Node.js installed on your machine

• 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:

$ nexmo setup api_key api_secret

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.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Forwarding a call to a Stitch 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 Stitch 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:

$ npm install express body-parser --save

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

'use strict';
const express = require('express');
const bodyParser = require('body-parser');
const app = express();
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({extended: true}));

const server = app.listen(3000, () => {
  console.log('Express server listening on port %d in %s mode', server.address().port, app.settings.env);
});

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

app.post('/event', (req, res) => {
  console.log(req.body);
  res.status(200).end();
});

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 rtc type to the endpoint in order to connect the call with an existing Stitch user. You can add your own phone number in the from field.

app.get('/answer', (req, res) => {
  var ncco = [
    {
      action: "talk",
      text: "Thank you for calling Jamie"
    },
    {
      "action": "connect",
      "from": "449876543210",
      "endpoint": [
        {
          "type": "rtc",
          "user": "jamie"
        }
      ]

    }
  ];
  res.json(ncco);
})

Now let's run the server:

$ node index.js

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:

$ 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 aaaaaaaa-bbbb-cccc-dddd-0123456789ab "My Voice App" https://6e5c2f7a.ngrok.io/answer https://6e5c2f7a.ngrok.io/event

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 449876543210 aaaaaaaa-bbbb-cccc-dddd-0123456789ab

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

Conclusion

Now that you've linked your number to your application, whenever someone calls your Nexmo number they are going to be connected to a Stitch 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 Stitch SDKs.

What's next?

If you'd like to continue learning how to use the Nexmo Stitch 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 Stitch we encourage you to join the Nexmo community slack and check out our #stitch channel or email us directly at ea-support@nexmo.com.