Qualify leads using AMD and IVR with Node.js

One popular use case for a Voice solution is to call numbers from a list or a database and qualify leads to see if they want to speak to a sales rep. With Sinch's Answering Machine Detection service, that's never been easier! This tutorial will walk you through how to create your own lead qualification app in Node.js.

What you need to know before you start

Before you can get started, you need the following already set up:

• Set all Voice API configuration settings.
• npm and a familiarity with how to install packages.
• Node.js and a familiarity with how to create a new app.
• ngrok and a familiarity with how to start a network tunnel. You can use any method you want to make your server accessible over the internet, but we like ngrok and it's what we'll use in this guide.
• Postman or another method of making API requests to a server on your machine. You can use whatever you like, but Postman makes things easy, and it's what we'll use in this guide.
• A SIP infrastructure. This is optional, as we realize not everyone has access to something like this. You can complete this tutorial without one.

Set up your Node.js application

Create and then navigate to a new folder where you want to store your project. Open a command prompt to that location and create a new node app with npm:

npm init

Accept the defaults for the application.

Install your dependencies

Use the following command to install the Express, ngrok, and node-fetch packages:

npm install express ngrok node-fetch

Create your file

In your project folder, create a new file named index.mjs in the project and paste the provided "index.mjs" code into the file.

This may seem like a lot of code, but don't worry! We'll explain what everything does as we go along. This code does quite a lot of things, but if we break it down it has these basic parts:

1. Configure your server
2. Make a custom callout
3. Handle callbacks with SVAML

Configure your server and callback URL

The first step is to configure your server to start on port 3000 of localhost.

Additionally, we also start an ngrok tunnel to that port so your server can communicate with the internet. At the same time we update the callback URL so that the Sinch servers can send callbacks to your server. This is handled by the following methods in the code you already copied:

const APPLICATION_KEY = 'YOUR_application_key';
const APPLICATION_SECRET = 'YOUR_application_secret';
const OUTGOING_NUMBER = 'YOUR_sinch_number'; //The Sinch number you'll be using to make the callout
const SIP_URI = 'YOUR_sip_endpoint'; //The number you want to connect the call to when a lead is qualified

const PORT = 3000;

const app = express();
app.use(express.json());

...

app.listen(PORT, async () => {
  const ngrokUrl = await ngrok.connect(PORT);
  console.log(`Node.js local server is publicly-accessible at ${ngrokUrl}/answer`);
  await updateUrl(ngrokUrl + '/answer');
  console.log(`Listening at http://localhost:` + PORT);
  ...
});

We also need to set a few configuration parameters to allow your server to connect to the Sinch servers. You can find most of the values you need on your dashboard.

Make a custom callout

To make a call out to a phone number, we need to make a callout. And because we're using AMD, we need to make a custom callout to start the lead qualification process. This is handled by the following methods in the code you already copied:

async function makeCallout(applicationKey, applicationSecret, number) {

    const calloutBody = {
        method: 'customCallout',
        customCallout: {
            ice: "{\"action\": {\"name\": \"connectPstn\", \"number\": \"" + number + "\", \"cli\": \"" + OUTGOING_NUMBER + "\", \"amd\": {\"enabled\": true }, \"locale\": \"en-US\" }}",
            enableAce: true,
            enableDice: true
        }
    };

    const resp = await fetch(
        `https://calling.api.sinch.com/calling/v1/callouts`,
        {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                Authorization: 'Basic ' + Buffer.from(`${applicationKey}:${applicationSecret}`).toString('base64')
            },
            body: JSON.stringify(calloutBody)
        }
    );
    const data = await resp.json();
    console.log(data);
}

Custom callouts use SVAML to create their own call events, depending on what's needed. In this case, we're using a custom callout to make an Incoming Call Event (or ICE) to connect your Sinch number to a phone number on the telephone network. We also specify that AMD is enabled, so when the call is picked up (or not), the service determines whether the call was picked up a human or by an answering machine and reports back either way.

Handle callbacks with SVAML

The real magic of this solution happens once the AMD service has determined that a human answers the phone. The AMD service reports back whether a human answers or not in an Answered Call Event (or ACE). This ACE has an AMD status that we can parse and using switch statements we can have different code execute depending on the status.

If a human answers, we want to play an Interactive Voice Response menu for them. If a machine answers, since a machine can't decide an option to pick in an IVR, we just want a simple message to play for the answering machine to record.

Additionally, we need to handle what happens when the IVR response is sent to the Sinch servers. For this tutorial, if you're using a SIP infrastructure, we want you to be able to connect to it as one of the options. If you're not using a SIP infrastructure, we still want to simulate what it would be like to pick a menu option and be transfered, so we'll play a message instead of connecting a call.

Start your server

Now with all that out of the way, you can start your server and get to the good stuff! Start your server with the following command:

node index.mjs

If you watch along in the console, you should see the server start on your specified port, the ngrok tunnel start, and a notice that your callback URL was updated on your app.

Make your callout and follow the prompts

http://localhost:3000/callout?number=<your-phone-number>

Now just follow the prompts on your phone. If at any time you want to follow the prompts a different way, simply hang up and make the callout again.

Next steps

Check out more of our Voice tutorials or take a look at the Voice API specification