Get started with Twilio’s Programmable Voice API to build an IVR system

A quick guide for building an interactive voice response (IVR) system for your customers with Twilio, Node.js, and Express

When you want to get ahold of someone, there’s nothing quite like giving someone a call. When that someone is a business, you want to connect to the right place with the minimum of fuss. That’s where an interactive voice response system comes in, otherwise known as an IVR. An IVR enables callers to speak or press digits on a touch-tone phone to quickly find the right person or information.

Twilio’s Programmable Voice API enables you to quickly build an engaging IVR with just a few lines of code. Though Twilio supports any language capable of talking to a REST API and has libraries for all the popular languages like Java and C#, I’m focusing this tutorial on Node.js.

Sign up and get a Twilio phone number

Before you can receive a phone call with Node.js, you’ll need to sign up for a Twilio account and purchase a phone number. If you sign up for the free trial, you’ll get your first phone number for free. If you search for a number to buy, you’ll be able to see what types of communication it can power (such as SMS, fax , and voice).

twiliovoice1 Andrew Baker/Twilio

Buy a phone number

Click the red Buy a Number button to add one of these numbers to your account. Now that you have a Twilio account and a programmable phone number, you can start writing code. To make it easier, install Twilio’s official helper for Node.js applications.

Install the Twilio Node.js module

Next, install the Twilio module for Node.js. Fire up a terminal or command-line interface on your computer that already has Node and NPM installed, and run the following command in a new directory:

npm install twilio

This will install the twilio module so Node.js code in your project can use it.

Responding to a phone call

To initiate the IVR, you need to configure one of your Twilio numbers to send your web application an HTTP request called a webhook when you get an incoming call.
Click on one of your numbers in the console and configure the Voice URL to point to your app. In the code the route will be /ivr/welcome.

twilio voice 2 Andrew Baker/Twilio

If you don’t already have a server configured to use as your webhook, ngrok is a great tool for testing webhooks locally.

With your Twilio number configured, you are prepared to respond to the Twilio request.

Respond to the Twilio HTTP request with TwiML

When Twilio sends a HTTP request to your app, it needs instructions in return as to what to do with that request, which it requires in the Twilio XML-like markup language TwiML. Your Twilio number is already configured to send HTTP requests to this route method on any incoming voice calls. Your app responds with TwiML to tell Twilio what to do in response to the message.

As you would expect from an IVR, the first thing you hear when the call is picked up is a message asking for input and then the caller.

Use the TwiML command <Play> to play the welcome message and <Gather> to gather the input from the caller so you can decide what to do next.

twiliovoice3 Andrew Baker/Twilio

</> Respond with TwiML to gather an option from the caller

After playing the audio and retrieving the caller’s input, Twilio will send this input to your application.

Where to send the caller’s input

The <Gather>’s action parameter takes an absolute or relative URL as a value—in this case, the /ivr/menu route.

To make it simple for this example, get the caller to enter digits, although you can use speech recognition to process and return speech to your app. When the caller has finished entering digits, Twilio will make a GET or POST request to this URL, including a Digits parameter with the number your caller chose.

After making this request, Twilio will continue the current call using the TwiML received in your response. Any TwiML verbs occurring after a <Gather> are unreachable, unless the caller enters no digits.

twiliovoice4 Andrew Baker/Twilio

</> Send caller input to the intended route

Now that you have told Twilio where to send the caller’s input, you can look at how to process that input.

Process the caller’s selection

This route handles processing the caller’s input.

If your caller chooses 1 for directions, use the helper method giveExtractionPointInstructions to respond with TwiML that will Say directions to your caller’s extraction point.

If the caller chooses 2 to call home, you need to gather more input from the caller. I’ll cover this in the next step.

If the caller enters anything else, respond with a TwiML Redirect to the main menu.

twiliovoice5 Andrew Baker/Twilio

</> Main menu and return instructions

If the caller chooses 2, take him or her to a directory where you collect more input.

Connect the caller to another number

If your callers choose to call home, will read them the planet directory. This is akin to a typical “company directory” feature of most IVRs.

In this route, grab the caller’s selection from the request and store it in a variable called selectedOption. Then use a Dial verb with the appropriate phone number to connect your caller to his or her home planet.

The current numbers are hard-coded, but they could also be read from a database or from a file.

twiliovoice6 Andrew Baker/Twilio

</> Read planet directory and connect to another number based on caller input

That’s it! You’ve just implemented an IVR phone tree that will delight and serve your customers.

If you want to try out adding speech recognition to your IVR, here’s a tutorial for that to try next. Prefer a different language or IVR feature? Try our IVR Tutorials page.

This article is published as part of the IDG Contributor Network. Want to Join?