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) with Autopilot.

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 an appropriate task. 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 template from the Twilio Console.
• Modify the bot to work with your Twilio account.
• Program and train the bot to perform some new tasks.
• Connect the bot to a Twilio phone number to deploy it as an IVR.
• Configure the IVR to contextually hand-off calls to a human agent.

1. Create a bot

We’ll be using the Hospitality template available in the Twilio console. Select the template in the Build a bot page to create the bot. This usually takes a few seconds.

2. Review the bot configuration

Tasks

The bot template comes with nine built-in tasks.

1.greeting

The default task triggered when the user greets the chatbot. You should train this task based on how you’re asking your users to begin interacting with the chatbot. This task also responds with a list of specific requests the bot can help the user with. This ensures the conversation is tightly scoped to what the bot has been trained for, increasing it's chances of successfully helping the user.

2.deliver_room_items

Asks the user which extra items they need delivered to their room. This task uses a Collect flow to gather this information from the user before redirecting to the complete_collect_roomitems that completes the request.

3.complete_collect_roomitems

Completes the user's request to deliver the extra items. Note that this task is programmed to keep the conversation alive by setting listen to true, which allows the user to end the conversation. This is a general best practice — you always want to give the user the option to initiate another request in the same dialogue.

4.order_roomservice

Asks the user for their room service order. This task also uses a Collect flow to gather this information from the user before redirecting to the complete_collect_roomservice task that completes the request.

5.complete_collect_roomservice

Similar to complete_collect_roomitems, completes the user's request to deliver the extra items. Note that this task is also programmed to keep the conversation alive by setting listen to true, which allows the user to end the conversation.

6.get_quantity

This task illustrates how you can use another mechanism for receiving a request to order more items — Field extraction. It's trained on a number of samples that can identify what item the user wants if they directly make their request instead of first greeting the bot. For example, if the user says "Can I have more towels?", the bot extracts "towels" from their request, follows up by asking for the quantity and triggers the complete_collect_roomitems task.

7.collect_fallback

This task is triggered if any of the Collect sequences used fail to handle the user's request. By default, it's configured to try again to help the user. However, you could modify it to hand-off to a live agent depending on the type of customer experience you're looking to create. Refer to How to hand-off messaging conversations from Autopilot to your Contact Center to see how to implement hand-off.

8.fallback

This task is triggered if your bot can't match the user's query to one of these 9 tasks. By default, it's also configured to try again to help the user. You could also similarly modify it to hand-off to a live agent depending on the type of customer experience you're looking to create. Refer to How to hand-off messaging conversations from Autopilot to your Contact Center to see how to implement hand-off.

9.goodbye

Ends the dialogue. Doing so erases any context stored in the Autopilot Memory and treats any subsequent requests from the user as a new dialogue.

Default Behaviors

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

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

In general, defaults should point either to:

• An existing task. With our airline reservation bot, the assistant_initiation default points to the welcome_message 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

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 four simple tasks using the console to our bot to allow the user to check out from the hotel and order a taxi. We'll then program and train these tasks to start helping users.

5. Program Tasks

1.self_checkout

Click the Add Task button on the task's list page and paste the JSON from the code snippet in the text editor, and click Save.

For the sake of simplicity, we’re programming this task to respond with a simple message. However, you could easily generate a more dynamic response that thanks the user by name for example. The easiest way to generate dynamic responses is to use Functions (see example 2).

2.order_taxi

We’ll program this task with a Collect flow that asks the user for their destination and pick up time. Click the Program button on the order_taxi task and paste the Collect flow from the code snippet in the text editor, and click Save. Once the bot collects the user's destination and pick up time, it triggers the complete_order_taxi task to complete the request.

3.complete_order_taxi

This task completes the user's request to order a taxi. Note that this task is programmed to keep the conversation alive by setting listen to true, which allows the user to end the conversation. You could also use a Function or your own server to generate a respose that inserts the user's destination in the bot's response. Sending the user's responses to another system, in this case a taxi dispatch system, would require a Function or a web server instead of the static JSON editor.

Click the Add Task button on the task's list page and paste the JSON from the code snippet in the text editor, and click Save. For the sake of simplicity, we’re programming this task to respond with a simple message.

4. send_to_front_desk

This task is used to transfer the call from the IVR to a live agent. It gets triggered when Autopilot detects that the customer is asking to speak to an agent, and is trained accordingly (more on that below). We'll program this task using a Twilio Function to illustrate how you can dynamically generate responses for Autopilot and use the handoff action to build the call transfer capability. 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.

Note that there are two ways you can hand off calls with Autopilot — using Programmable Voice and Taskrouter/Flex. You should use Programmable Voice if you're not using Taskrouter or Flex in your contact center.

Go to the Manage Functions page in the Twilio console here and create a new function. If you're handing off using Programmable Voice, paste the code from the send_to_front_desk_pv code snippet into the editor. Next, you need to modify this code to work with your account. Programmable Voice also requires a URL that returns valid TwiML to complete the hand-off. The easiest way to set this up is by creating a TwiML Bin. Go to the console here, create a new TwiML Bin and paste the code included in the send_to_front_desk_twiml code snippet into the editor. Copy the unique URL for the TwiML bin and click Save. Go back to the Function and paste this URL in the uri attribute in the Actions JSON. You can also set up an URL for the voice_status_callback_url, but this is optional.

If you're using Taskrouter and Flex, paste the code from the send_to_front_desk_flex code snippet into the Functions editor. Point the URI attribute to your task router workspace using the Workflow SID as shown in the snippet. You can find this in the Taskrouter console within your Workspace. You can also add a wait_url if you want to play custom hold music, but this is optional.

Next, create a new Autopilot task called send_to_front_desk in the console. Instead of programming it using the ActionBin, toggle to the Actions URL and paste the URL of the Function you just created. Now Autopilot will make requests to this Function when the send_to_front_desk task is triggered to execute the hand-off.

Also note that when Autopilot executes the Handoff Action to transfer the call using Programmable Voice, it provides the entire context of the conversation via the Memory parameter included in the request it makes to the TwiML URL provided. Learn more about how Autopilot makes requests here. When it executes the Handoff Action using Taskrouter and Flex, it automatically adds the request data to the Task Attributes of the Task created in your Workspace as a result of the handoff. Learn more about Task Attributes here.

6. Train Tasks

Next, we need to train these tasks using example phrases your users might say to the bot to check out of the hotel or request a taxi. Training is an essential part of building a bot powered by machine learning. Under the hood, each bot 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. In this case, we don't need to train the complete_order_taxi task.

Click on the Train button next to the task to open up the training menu and add your Samples.

order_taxi

You can train this task with samples like:

• I'd like to order a cab
• Can I get a taxi
• Please order a taxi for me
• Cab service
• Taxi service
• Can I get a taxi to the airport
• Airport cab service
• Taxi
• Please get me a cab

self_checkout

You can similarly train the self_checkout task with samples like:

• Check out
• I'd like to check out
• Can you help me check out
• I want an early check out
• Can you check me out of my room?

send_to_front_desk

You can similarly train the send_to_front_desk task with samples like:

• Can I talk to an agent?
• Agent
• I want to talk to someone
• Talk to a representative
• Concierge
• Talk to concierge
• Can I talk to someone?
• I'd like to talk to an agent
• Concierge please
• Representative

7. Build a 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. The alert will automatically be displayed when you make changes to your bot's configuration. Click Build model to update the bot with your changes.

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

8. Configure a Twilio Phone Number

Go to Channels in your Autopilot console and click on Programmable Voice. Copy the Voice 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. Click Save.

Congratulations! You've connected your Autopilot bot to a Twilio phone number. Call your number to test your new conversational IVR.

9. Keep Building

• Add some more tasks, like a customer interaction satisfaction survey or the ability to check-in to your hotel.
• Learn how to add DTMF support to conversational IVRs.
• Learn how to train bots in production.
• Understand how Task Confidence works.
• Explore the Autopilot documentation.
• Get familiar with the Autopilot CLI.