Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

How to build a conversational IVR

This guide will give you the resources and information you need to build a conversational IVR (Interactive Voice Response.)

Autopilot uses a task-driven programming model where tasks correspond to outcomes the user wants from interacting with your IVR, like booking an appointment, planning a reservation, or changing a flight. It uses natural language understanding (NLU) to detect what your users are saying and match it to the appropriate task. Your IVR can be trained to recognize different possible phrases and words the user could say that correspond to a task. With pre-built-AI-templates and powerful NLU tools, the heavy lifting is out of the way so you don't need to worry about reducing operation costs and increasing customer satisfaction.

Instead of requiring your users to provide exact responses or keywords to interact with your IVR, the IVR can be trained to parse and/or recognize similar phrases or words.

In this guide, we’re going to:

  • Create an Autopilot bot with a pre-built template using the Autopilot Command Line Interface (CLI)
  • Modify the bot to work with your Twilio account
  • Deploy the bot as an IVR
  • Program and train the IVR to perform some new tasks and route callers accordingly

1. Install the Autopilot CLI with npm

Start by installing the Autopilot CLI. This will allow you to quickly create an Autopilot bot in your account using the template provided.

Install the CLI with this command:

sudo npm install -g @twilio/autopilot-cli

Get npm if you don’t already have it installed.

After Autopilot CLI is installed, configure the CLI with your Twilio account credentials:

ta init

Your credentials will be stored in a local JSON file at ~/.twilio/config.json. You can learn more about the different commands supported by the CLI here.

2. Create a Bot

In this guide, we’ll be creating a bot that helps users with their Disneyland vacation reservations. The Autopilot CLI comes with different templates you can use to jump-start your development. You can find this template, as well as others for different use cases, in the Autopilot templates GitHub repository.

Once you’ve installed the Autopilot CLI, use the ta create command to create a new bot in your account from a template.

Disneyland Vacation template ta create in CLI

If you have added multiple credentials to the CLI, you can provide the profile name to select the Twilio account you want to use:

ta create [--schema <file>] [--credentials <profile-name>]

Select Disneyland Vacation in the command line and the CLI will create a new bot with the same name in your account. You can always change its name later as you see fit.

Bot created in console

3. Configure a Twilio Phone Number

Go to Channels in your Autopilot console and click on Programmable Voice. Copy the Voice URL.

Voice channel URL

If you don't have a Twilio phone number yet, open a new tab and buy one now. Scroll down to the Voice & Fax section and paste the Autopilot URL you copied in the A call comes in box next to Webhook.

Configure Twilio Number with Autopilot URL Voice

Click Save and tada! Your Twilio phone number is configured for voice with Autopilot.

4. Modify the Bot Behavior

Let’s review how the bot you just created from the template is set up and make a few small changes to make it work in your Twilio account.


This IVR template comes with four built-in tasks.

Program Tasks and set default behaviors

1. vacation_greeting

The default task triggered when the user first calls in. This is configured by setting it as the initiation task in the Default Behaviors for your IVR. It dictates what the caller hears first when the IVR answers their call.

You should train this task based on how you're asking users to begin interacting with the IVR. For example, the task in the template has been trained on phrases like 'hi' and 'hello', so some samples you could train it on could include 'what's up', etc. See Step 4 for more details on training.

Greeting the IVR isn't mandatory. If the user already knows what they want, like checking today's schedule for example, Autopilot will skip this task and directly kick off the todays_schedule task.

2. todays_schedule

Returns a hard-coded schedule for the day. You could also write a Twilio Function that "retrieves" data parsed from a webpage or an API, and then constructs a personalized response for Autopilot to deliver to the user.

We will use Functions for the next task.

3. buy_tickets

This task uses a Collect flow to gather this information from the user before redirecting to a Twilio Function that saves their reservation details and constructs a personalized response for Autopilot to deliver to the user.

collect URI

Upon completion, this task will redirect to a Twilio Function. Functions provide a serverless environment for writing event-driven code using node.js to build dynamic Twilio applications. Each Function has a unique URL that can be invoked by an HTTP request to run the code.

You’ll need to create a new Function in your account and point it to the uri attribute in the buy_tickets task.

Go to the Manage Functions page in the Twilio console here.


Paste the code from `reservation-function` as shown on the right and click save.


        4. connect_human

        Uses a Say followed by a Handoff flow to connect the caller with a real human. This is an example of a hybrid task — starts off being handled by an IVR but is ultimately completed by the agent.

        Hybrid Tasks

        In a hybrid task, the IVR or bot handles a portion of the request before handing off to an agent. This guide doesn’t discuss implementing hybrid tasks but they are discussed more in How to hand-off messaging conversations from Autopilot to your Contact Center.

        Go back to Twilio Functions and click the red plus button to create a new Function. Put the JavaScript code for dial-response-node-connect-call in your new Function.


              Then take note of the URL under Properties near the top.


              Copy this URL and paste it in your task code below.


              Default Behaviors

              Defaults determine your bot's behavior in three different situations:

              • Bot Initiation: the bot is responsible for beginning a conversation. Only used for inbound phone calls.
              • Fallback: the natural language engine cannot map human input to an existing task and needs to provide the user with additional direction.
              • Collect on Failure: the assistant needs to know which task to use if there is a failure when collecting data.


              Defaults should point either to:

              • An existing task. With our Disneyland Vacation bot, the assistant_initiation default points to the vacation_greeting task.
              • A publicly accessible URL that responds with Actions. With our bot, the fallback points to a Twilio Function.

              Learn more about Defaults in the documentation.


              StyleSheets enable you to give your bot a style by specifying its voice, error messages, success messages, and data collection validation behavior.

              Learn more about Stylesheets in the documentation.


              4. Add Tasks

              We're going to add one simple task to our bot using the console to allow the user to explore character breakfast options for the day they would like.


              Create your explore_character_breakfast_options Task.

              We'll program this task with a Collect flow that asks the user which day of the week they would like to have a character breakfast on to retrieve dining options. Click the Program button on the explore_character_breakfast_options task. Paste the Collect flow from explore_character_breakfast_options_json in the text editor and click Save.


                    This flow uses the Validate feature in the Collect Action to ensure the user provides a valid day of the week. Learn more about Validating information provided by users in the documentation.

                    This task redirects the conversation to a Function to dynamically provide dining options based on the day selected by the user. These options have been hardcoded for simplicity. To create the Function, go to the Manage Functions page in the console here and paste the code under explore_character_breakfast_options_function_js in the editor:


                          Finally, point the uri attribute in the on_complete section of the Collect flow in the explore_character_breakfast_options task in Autopilot to the path generated by the Function (your Function path will be different as each path is unique to a user).

                          6. Train Tasks

                          Next, we need to train these tasks using example phrases your users might say to the IVR to check their loyalty status or check dining options. Training is an essential part of building a IVR powered by machine learning. Under the hood, the IVR uses a number of different machine learning models to process what the user is saying. These models need to be ‘trained’ with real examples of what your users might say when interacting with it. These examples are referred to as Samples in Autopilot.

                          We recommend starting with at least ten Samples, but the more you add, the more accurately your assistant will be able to match what the user said to the right task.

                          Click on the Train button next to the task to open up the training menu and add your Samples. Now you can add multiple training samples at once by clicking the Expand button below.



                          You could train this connect_human task with additional samples like:

                          • I wish to speak to a human
                          • Human
                          • Connect me to someone else
                          • Could I talk with someone else
                          • Do you think I could talk with someone else please



                          You can train this task with samples like:

                          • You can train this task with samples such as:
                          • What are my character breakfast options?
                          • Character breakfast restaurants
                          • Where can I get a character breakfast?
                          • Character breakfast options
                          • Breakfast
                          • Where can we get a character breakfast
                          • Eat while meeting characters
                          • Character meals
                          • My family would like a character breakfast
                          • Eat and greet with characters


                          7. Build a Model

                          When you’ve added new Tasks and Samples, you’ll see an alert at the top of the console to build a new model. Alternatively, navigate to the Logs in the left-hand navigation to build a new model. Building a model adds the training data you just provided to the IVR's machine learning model. When you make changes to your training data, like adding and deleting samples and fields, or add new Tasks or change Task names, remember to build a new model each time so these changes take effect.


                          Congratulations! You’ve successfully programmed and trained your IVR to perform new tasks for the user. You can now test it using the Voice Simulator in the console.


                          You can't see much if you don't test it yourself with the Voice Simulator, so you can also try the SMS simulator.


                          Lastly, you could call the Twilio number that you configured above from your personal phone number as well for a voice-powered IVR.

                          8. Keep Building

                          Rate this page:

                          Need some help?

                          We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.