Set Up a Node.js Dev Environment for Voice Calls

This guide shows how to set up a development environment in five minutes to trigger API requests and start serving Plivo XML to control your call flow. It also shows how to test your code using tunneling software to expose the local dev server to the public internet.

Install Node.js, the Plivo Node.js SDK, and Express

To get started, install Node and Plivo’s Node SDK. In macOS, Linux, or Windows you can check whether Node is installed by running the command node -version in a terminal window. If you need to install or update it, download and install it.

To install the Plivo Node.js SDK, first create a project directory using command mkdir mynodeapp, then change to the directory and install the SDK using npm:

  $npm install plivo

You should also install the Express framework.

Trigger an API request

Now you can create a file in the project directory and execute code to trigger any Plivo API. Here’s some example code that makes an outbound call. Create a file called Makecall.js and paste into it this code.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
var plivo = require('plivo');

(function main() {
    'use strict';

    var client = new plivo.Client("<auth_id>","<auth_token>");
    client.calls.create(
        "<Caller_ID>", // from
        "<Destination_Number>", // to
        "http://s3.amazonaws.com/static.plivo.com/answer.xml", // answer url
        {
            answerMethod: "GET",
        },
    ).then(function (response) {
        console.log(response);
    }, function (err) {
        console.error(err);
    });
})();

Save the file and run it.

node Makecall.js

You can follow the same approach to trigger other API requests. Refer to our detailed API reference to see all the API requests available on the Voice API platform.

Serve an XML document and manage callbacks

When you receive a call on a Plivo voice-enabled number, you can control the call flow by declaring an Answer URL for the Plivo application associated with that phone number. Plivo will invoke the Answer URL specified and expect a valid XML response to handle the call.

In addition to requests to the Answer URL, Plivo initiates other HTTP requests to your application server based on specific XML elements in your Answer XML document. Such requests are broadly classified into two categories:

Action URL requests: These requests are typically invoked at the end of an XML element’s execution, and the server expects XML instructions to carry forward the call in response to these requests. This happens, for example, when a caller provides Touch-Tone input during GetInput XML execution.

Callback URL requests: These requests serve as webhooks to pass the application server information about events through the course of an XML element’s execution, such as when a conference participant is muted or unmuted. No XML instructions are expected in response to these requests.

Set up a Express server to serve XML and manage callbacks

Here’s how to set up a Express server to serve XML documents and manage callbacks.

Use this code snippet to start a local server.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
var plivo = require('plivo');
var express = require('express');
var app = express();

app.all('/receive_call/', function(req, res) {
    var response = plivo.Response();
    var speak_body = "Hello, you just received your first call";
    response.addSpeak(speak_body);
    res.writeHead(200, {'Content-Type': 'text/xml'});
    res.end(response.toXML());
})

app.set('port', (process.env.PORT || 5000));
app.listen(app.get('port'), function() {
    console.log('Node app is running on port', app.get('port'));
});

Save this code in any file — we called ours receive_call.js. To run this file on the server, go to the folder where this file resides and enter:

node receive_call.js

You should see your basic server app in action on http://localhost:5000/receive_call/.

Ngrok setup

To serve XML documents, your local server must connect with Plivo API services. For that, we recommend using ngrok, which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server.

Install ngrok and run it on the command line, specifying the port that hosts the application on which you want to receive messages (5000 in this case):

   ./ngrok http 5000

This will start the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network.

You should be able to see your basic server app in action at https://<nrgok_URL>/inbound/.

You can follow the same approach to serve other XML documents to manage call flows. Refer to our detailed XML reference to check all the XML elements available on the Voice API platform.