Voice - call tracking

We live in a world of data and analytics where we use unique identifiers to measure the impact of past decisions in order to fine tune future ones. You can use phone numbers in this way too. For example, you track the most popular phone numbers used for television radio, magazine, print or online advertising, and the times those phone numbers are used, in order to improve future campaigns.

This tutorial is based on the Call Tracking use case. You download the code from https://github.com/Nexmo/node-call-tracker.

In this tutorial

In this tutorial you see how to build an application that keeps track of inbound calls using Nexmo APIs and libraries:

Prerequisites

In order to work through this tutorial you need:

  • A Nexmo account
  • The Nexmo CLI installed and set up
  • A publicly accessible web server so Nexmo can make webhook requests to your app. If you're developing locally we recommend ngrok.

Create a Voice application

A Nexmo application contains the security and configuration information you need to connect to Nexmo endpoints and easily use our products. You make calls to a Nexmo product using the security information in the application. When you make a Call Nexmo communicates with your webhook endpoints so you can manage your call.

You first use Nexmo CLI to create an application for Voice API:

› nexmo app:create call-tracker https://example.com/track-call https://example.com/event

Application created: 5523f9df-05bb-4a93-9427-6e43c32449b8

This command returns the UUID (Universally Unique Identifier) that identifies your application.

The parameters are:

  • call-tracker - the name you give to this application
  • https://example.com/proxy-call - when you receive an inbound call to your Nexmo number, Nexmo makes a GET request and retrieves the NCCO that controls the call flow from this webhook endpoint
  • https://example.com/event - as the call status changes, Nexmo sends status updates to this webhook endpoint

Then start your Web server:

var app = require('express')();
var config = require('../config');

app.set('port', (config.port || 5000));
app.use(require('body-parser').json());

app.listen(app.get('port'), function() {
  console.log('Example app listening on port', app.get('port'));
});

If you're developing behind a firewall or a NAT, use ngrok to tunnell access to your Web server.

Buy Voice Enabled Phone Numbers

For call tracking to function you need one or more Nexmo numbers to track. Use the Nexmo CLI to buy the phone numbers:

nexmo number:buy --country_code US --confirm
Number purchased: 15554908975

Now link each phone number with the call-tracker application. When any event occurs relating to a number associated with an application Nexmo sends a request to your webhook endpoints with information about the event.

nexmo link:app 15554908975 5555f9df-05bb-4a99-9427-6e43c83849b8

Handle inbound voice calls

When Nexmo receives an inbound call to your Nexmo number it makes a request to the webhook endpoint you set when you created a Voice application.

Extract to and the from from the inbound webhook and pass this to your call tracking logic.

var CallTracker = require('./CallTracker');
var callTracker = new CallTracker(config);

/**
 * Webhook endpoint to handle a call being answered.
 * Return an NCCO to record a call and proxy it to another number.
 */
app.get('/answer', function(req, res) {
  var from = req.query.from;
  var to = req.query.to;

  var ncco = callTracker.answer(from, to);
  return res.json(ncco);
});

Track the Call

The workflow for call tracking is:

Track the call and keep a count of how many times the from phone number has been called.

/**
 * Create a new instance of a CallTracker.
 *
 * @param {Object} config - CallTracker configuration.
 */
function CallTracker(config) {
  this.config = config;

  this.trackedCalls = {};
}

/**
 * Track the call and return an NCCO that proxies a call.
 */
CallTracker.prototype.answer = function (from, to) {
  if(!this.trackedCalls[to]) {
    this.trackedCalls[to] = [];
  }
  this.trackedCalls[to].push({timestamp: Date.now(), from: from});

Proxy the Call

Now your application has tracked the call information, proxy the call to the intended recipient. Keep the from number the same so the recipient has the correct contact details:

Build a Nexmo Call Control Object (NCCO) that instructs Nexmo to connect the call to another phone number. Keep the from number the same for the proxied call.

/**
 * Track the call and return an NCCO that proxies a call.
 */
CallTracker.prototype.answer = function (from, to) {
  if(!this.trackedCalls[to]) {
    this.trackedCalls[to] = [];
  }
  this.trackedCalls[to].push({timestamp: Date.now(), from: from});

  var ncco = [];

  var connectAction = {
    action: 'connect',
    from: from,
    endpoint: [{
      type: 'phone',
      number: this.config.proxyToNumber
    }]
  };
  ncco.push(connectAction);

  return ncco;

Note: take a look at the NCCO reference for information.

Your web server provides Nexmo with this NCCO and the Call is proxied to the to phone number.

/**
 * Webhook endpoint to handle a call being answered.
 * Return an NCCO to record a call and proxy it to another number.
 */
app.get('/answer', function(req, res) {
  var from = req.query.from;
  var to = req.query.to;

  var ncco = callTracker.answer(from, to);
  return res.json(ncco);
});

Conclusion

And that's it. You have built a call tracking application that enables you to determine the most popular number for inbound calls. To do this you have provisioned and configured numbers, handled an inbound call, stored and tracked the inbound call and proxied that call to another user.

Previous   Next