Add a Call whisper to an inbound call

Phone numbers are everywhere in advertising: on billboards, in TV ads, on websites, in newspapers. Often these numbers all redirect to the same call center, where an agent needs to inquire why the person is calling, and where they saw the advert.

Using call whispers, the context of the incoming call is announced to the call center operator before being connected to the caller. This guide will show an application that implements this approach. A user will call one of two numbers. The application answers the call and the caller hears a holding message. Meanwhile, the application also makes a call to the call center operative, plays a different call whisper depending on which number was dialled, and then connects the operative to the conference with the incoming caller.

The examples are written in node.js with express, and you can find the code on GitHub.

In this guide

You will see how to build add a Call Whisper to an inbound call:

  • How it works - an overview of who is calling who and how the process flows throughout the example application.
  • Before you begin - set up the application and numbers needed for this guide.
  • Getting started with code - clone the repository and get the application running.
  • Code walkthrough - dive in to the finer points of how the application works.
  • Further reading - check out some other resources that you might find helpful.

How it works

OperativeApplicationVonage numberUserOperativeApplicationVonage numberUserWhen operativeanswersCallers are connectedUser calls either ofthe numbers linked to this Application/answerConnects to operative's number/answer_outboundAnnounces key informationabout original caller

Before you begin

Before we grab and run the code, there are a few things we need to do first.

Sign up for Vonage

Sign up for a Vonage API account if you don't have one already.

Set up the CLI

This guide uses the Vonage command line tool, so check it is installed before proceeding.

Create a Voice application

Use the CLI to create a Voice API application with the webhooks that will be responsible for answering a call on your Vonage number (/webhooks/voice/answer) and logging call events (/webhooks/voice/event), respectively.

These webhooks need to be accessible by Vonage's servers, so in this guide you will use ngrok to expose your local development environment to the public Internet. This article explains how to install and run ngrok and configure Vonage to send requests.

If you do not have an application, you can create one using the CLI

vonage apps create 'Your application'

✅ Creating Application
Saving private key ... Done!
Application created

Name: Your application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
  None Enabled

The command returns an application ID (which you should make a note of) and your private key information (which you can safely ignore for the purposes of this guide).

Run ngrok using the following command:

ngrok http 3000

Make a note of the temporary host name that ngrok provides and use it in place of example.com in the following command:

vonage apps capabilities update 00000000-0000-0000-0000-000000000000 voice `
  --voice-answer-url='https://example.com/webhooks/voice/answer' `
  --voice-event-url='https://example.com/webhooks/voice/event' `
  --voice-fallback-url='https://example.com/webhooks/voice/fallback'
  
✅ Fetching Application
✅ Adding voice capability to application 00000000-0000-0000-0000-000000000000

Name: Your application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
 VOICE:
    Uses Signed callbacks: On
    Conversation TTL: 41 hours
    Leg Persistence Time: 6 days
    Event URL: [POST] https://example.com/webhooks/voice/event
    Answer URL: [POST] https://example.com/webhooks/voice/answer
    Fallback URL: [POST] https://example.com/webhooks/voice/fallback

Buy a phone number

To handle inbound calls to your application, you need a number from Vonage. If you already have a number to use, jump to the next section to associate the existing number with your application.

You can use the Vonage CLI to buy the phone number:

Search for a Number

You can purchase a number using the Vonage CLI. The following command searches for a number a purchase (specify an alternate two-character country code to purchase a number in another country).

vonage numbers search US

✅ Searching for numbers

There is 1 number available for purchase in United States

Number       Type    Features         Monthly Cost  Setup Cost
-----------  ------  ---------------  ------------  ----------
16127779311  Mobile  MMS, SMS, VOICE  €0.90         €0.00

Use vonage numbers buy to purchase.

Purchase a number

Once you have found a number you are satisfied with, you can purchase that using the vonage numbers buy command:

vonage numbers buy US 16127779311 
✅ Searching for numbers
Are you sure you want to purchase the number 16127779311 for €0.90? [y/n] y

✅ Purchasing number
Number 16127779311 purchased

Number: 16127779311 
Country: 🇺🇸 United States
Type: Mobile
Features: MMS, SMS, VOICE
Monthly Cost: €0.90
Setup Cost: €0.00
Linked Application ID: Not linked to any application
Voice Callback: Not Set
Voice Callback Value: Not Set
Voice Status Callback: Not Set

Note For this guide, you will need two numbers

Getting started with code

The code for this project is on GitHub. This consists of a node.js project using Express and is intended to give you a working example that you can then adapt for your own needs.

Clone the repository

Either clone or download the repository to your local machine, in a new directory.

Configure the settings

Your application will need to know more about you and your application before it can run. Copy the .env-example file to .env and edit this new file to reflect the settings you want to use:

  • CALL_CENTER_NUMBER: The phone number to reach the call center operative on, such as your mobile number
  • INBOUND_NUMBER_1: One of the numbers you purchased
  • INBOUND_NUMBER_2: The other number you purchased
  • DOMAIN: The domain name of where your app will be running, for example mine is: ff7b398a.ngrok.io

Install the dependencies

In the directory where you downloaded the code, run npm install. This brings in Express and other dependencies needed for this project.

Start the server

With the configuration done and the dependencies in place, your application is ready to go! Run it with:

npm start

By default, the application runs on port 3000. If you're going to be using ngrok, you can start your tunnel now.

When the ngrok tunnel name changes, remember to update your application's URLs with the vonage apps capabilities update command.

Try it out

Let's try the demo. For this you need two phones (one to be the "caller" and one to be the "call center operative") so you may need to recruit a friend or use Skype to make the first call.

  1. Call one of the numbers you purchased.
  2. The caller will hear a greeting message, and then the call center operative's phone number will ring.
  3. When the call center operative answers, they will hear the "whisper" message before they are connected to the original caller.
  4. Now try that again but call the other number and listen to the different "whisper".

Code walkthrough

The demo is fun but if you're interested in building this yourself, then there are some key points that you probably want to see. This section looks at the key sections of the code for each step of the process so that you can find where things take place and can adapt this application to suit your needs.

Answer the incoming call, and start an outbound call

Whenever someone calls one of the numbers that are linked to the Vonage application, Vonage will receive an incoming call. Vonage will then notify your web application of that call. It does this by making a webhook request to your web app's answer_url endpoint - in this case /answer. When the call is answered, the application connects that caller to the call center operative.

lib/routes.js

app.get('/webhooks/voice/answer', (req, res) => {
  const  answer_url = 'http://'+process.env['DOMAIN']+'/on-answer'
  console.log(answer_url);

  res.json([
    {
      "action": "talk",
      "text": "Thanks for calling. Please wait while we connect you"
    },
    {
      "action": "connect",
      "from": req.query.to,
      "endpoint": [{
        "type": "phone",
        "number": process.env['CALL_CENTER_NUMBER'],
        "onAnswer": {"url": answer_url}
      }]
    }
  ]);
});

Note: Take a look at the Voice API reference for more info.

The response we return is an array of NCCOs (Nexmo Call Control Objects). The first one is the spoken message that the caller hears; the second connects to the other caller and specifies which URL should be used when that person answers the call.

Play a Whisper and Connect the Call

When the call center operative answers the call, the onAnswer URL is used, in our application that's the /on-answer endpoint. This is the code that looks up which number was dialled and works out what announcement to make.

lib/routes.js

// Define the topics for the inbound numbers
const topics = {}
topics[process.env['INBOUND_NUMBER_1']] = 'the summer offer';
topics[process.env['INBOUND_NUMBER_2']] = 'the winter offer';

When the call is connected, play a call whisper to the agent using the talk NCCO action, informing them which advertising campaign the call is about, before connecting them to the caller waiting in the conference.

lib/routes.js

app.get('/on-answer', function(req, res) {
  // we determine the topic of the call based on the inbound call number
  const topic = topics[req.query.from]
  res.json([
    // We first play back a little message telling the call center operator what
    // the call relates to. This "whisper" can only be heard by the call center operator
    {
      "action": "talk",
      "text": "Incoming call regarding "+topic
    }
  ]);
});

There are so many possibilities here that can help you to customize the whispers. You could pass the incoming caller's number with the url in on-answer and look them up, allowing you to greet them by name or provide some other information. The possibilities are endless but hopefully this guide gives you a working example you can build on and customize.

Further reading

  • GitHub contains all the code for this example application.
  • Check out our Voice Guides for more things you can do with voice.
  • The Voice API Reference has detailed documentation for each endpoint.