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 hand-off messaging conversations from Autopilot to your Contact Center

To hand off voice calls from Autopilot to your Contact Center, use the Handoff Action. This guide shows you how to hand off messaging conversations, which require an approach different from voice calls.

This guide will give you the resources and information you need to know to hand-off messaging conversations.

The ability to hand-off tasks from a bot to a human agent is critical to building bot experiences that don’t frustrate your users. There will be situations your bot is not equipped to handle that should be escalated to an agent. You may also need to build hybrid customer journeys where the bot handles a part of the customer request before handing off to a human being to complete it like the example of booking a flight we’ve used here. With Autopilot, you can hand-off messaging conversations from a bot to human agents with the entire context of the customer conversation intact.

In this guide, you’re going to:

  • Create an Autopilot bot with a pre-built template using the Autopilot Command Line Interface (CLI).
  • Set up the bot to work with your Twilio account.
  • Use the Autopilot Studio Widget to add the bot to a Studio flow.
  • Implement simple logic in the Studio flow to facilitate agent handoff.
  • Deploy the bot on the messaging channel and contact center of your choice.

Twilio Studio is a visual builder for communications workflows. It provides a number of different widgets that you can arrange in a drag-and-drop interface to build custom communications workflows over messaging or voice.

Building Chatbots with Autopilot

If you’ve already followed the How To Build a Chatbot guide, you can skip steps 1 and 2 because they are identical.

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 airline 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 repository on GitHub.

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


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 AirlineReservations 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 List.png

3. Set up the Bot

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


The bot template comes with five built-in tasks.

Task List.png


The default task triggered when the user greets the chatbot. You should train this task based on how you’re asking your users to start interacting with the chatbot. For example, the task in the template has been trained on phrases like ‘Start’, ‘Hello’ and ‘Begin’, so some samples you could train it on could include ‘Let’s start', ‘Hey there’, 'Time to begin', etc. See Step 4 for more details on training.

Greeting the bot isn’t mandatory. If the user already knows what they want, like checking their flight time for example, Autopilot will skip this task and directly kick off the get_flight_time task.


Asks the user for their name and departure city to retrieve their reservation details. Note that the departure and arrival times for the flight have been hard-coded for simplicity. This task uses a Collect flow to gather this information from the user before redirecting to a Twilio Function that ‘retrieves’ their flight details and constructs a personalized response for Autopilot to deliver to the user.

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.

Get Flight Time.png

You’ll need to create a new Function in your account to get this task to work.

Go to the Manage Functions page in the Twilio console here and paste the code included below in the editor, and click Save:


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



        This task is essential for building hand-off to Flex or any other contact center platform. It gets triggered when Autopilot recognizes that the user wants to skip the chatbot and talk directly to an agent. We do this by training it on phrases that a customer might say to want to talk to an agent (see Step 4 for more details on training). It is also used by the two hybrid tasks described below - book_flight and change_flight to hand off the conversation to an agent.


              You’ll need to modify this task to work in your Twilio account. It currently uses a Twilio Function from the account used to create the bot template. You’ll need to replace this with a new Function from your account.

              Go to the Manage Functions page in the Twilio console here and paste the code included below in the editor, and click Save:


                    This function adds a new variable called sendToAgent to your bot's memory to indicate that the conversation needs to be handed off to an agent. Autopilot provides the current memory of the bot as a JSON object in each request it makes to your application. The Autopilot Studio widget also passes this request data to the Studio Flow used by Flex, allowing you to parse this variable to execute the hand-off. We’ll cover this in Step 6.

                    Finally, go back to the send_to_agent task and point the redirect action to the unique path generated for your Function.

                    send to agent.png


                    Uses a simple Collect flow to ask the user for their departure city, destination city, departure date and if this is a round-trip, confirms if the information collected is accurate and hands the task off to an agent to complete the booking. This is an example of a hybrid task where a chatbot collects the relevant data from the customer and the agent completes the task using the collected data.


                          When the bot completes this Collect flow, it follows the on_complete instructions to make a POST request with the collected info to a Twilio Function which generates a confirmation message that the bot sends back to the user.

                          You’ll need to create a new Function in your account to make this work. Go to the Manage Functions page in the Twilio console here and paste the code included below in the editor, and click Save:


                                Finally, point the redirect attribute in the on_complete section of the Collect flow to the unique path generated by your Function:



                                This task immediately hands the user off to an agent to process changing their flight as shown below.


                                      To get it to work in your account, point the redirect action to the unique URL of the Function you just created for the send_to_agent task.

                                      Default Behaviors

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

                                      • Assistant 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 bot needs to know which task to use if there is a failure when collecting data.

                                      default behaviors.png

                                      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 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. Train Tasks

                                      Next, we need to train the tasks we’ve configured in Step 3 with phrases your users might use to trigger them. 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 called Samples in Autopilot.

                                      Each task in this Assistant template already comes with a number of different samples. To view Samples for the book_flight task for example, click on the Train button next to the task.


                                      You can also add more samples to this task using the text box if you want. You could add phrases like 'I need to book a flight', 'Find me a flight' and 'Get flight' for example.

                                      Go to the Training mode for each of the other tasks to view existing Samples and add new ones.

                                      5. Build Model

                                      build a model.png

                                      Next, hit the Build model button that will pop up in an alert. 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.

                                      Congratulations! You’ve successfully programmed and trained your bot.

                                      6. Build Agent Hand-off

                                      Now that you have trained and programmed the bot, you need to add it to a Studio Flow to implement agent hand-off.

                                      To build agent hand-off, you’ll use the Autopilot, Split Based On, Send Message and SendMessageToFlex (if you’re using Flex) or HTTP Request (if you’re using another contact center platform) widgets.

                                      Note that the approach you should follow depends on whether you're use Flex or not.

                                      Without Flex: Create a Studio Flow and add the Autopilot widget to it

                                      If you’re not using Flex as your contact center platform, you’ll need to first create new Studio Flows for Messaging and Programmable Chat, and add the Autopilot Widget to it.

                                      For Programmable Chat

                                      Go to the Studio Dashboard, hit the New Flow button, name your flow, and choose ‘Start from scratch’ as your template.

                                      create studio flow.png

                                      Drag and drop the Autopilot Widget into the canvas from the widget tray. Name your widget and select the bot you want to use from the drop down.


                                      The Messaging & Chat Config comes with a few default values. For Chat, you should replace the default value in the ‘Send Message From’ field with the name of your bot. This ensures that the name of your bot is displayed with the messages it sends in the chat channel.


                                      For Messaging

                                      Follow the same steps to create another flow for Messaging with one modification. Do not change the ‘Send Message From’ field in the Messaging & Chat Config. With Messaging channels, we want Studio to use the default channel address, which maps to the phone number, WhatsApp phone number or Facebook Messenger profile. Your messages will fail if you change this value.

                                      With Flex: Add the Autopilot widget to the default Webchat and Messaging Flows for Flex

                                      If you’re using Flex, you need to add Autopilot to the default Webchat and Messaging Flows Flex created when you first deploy it. Make sure you only use the default Messaging and Webchat Flows.

                                      Learn more about these Flows here.

                                      For Webchat


                                      Drag-and-drop the Autopilot widget between the Trigger and SendMessageToFlex widgets. Click on the widget and select your Assistant from the drop down. Click into the Messaging & Chat Config and change the value in the Send Message From field to the name of the Assistant you want to appear in the chat.

                                      For Messaging

                                      The configuration for messaging channels when you're using Flex is different from when you're not using it. Drag-and-drop the Autopilot widget between the Trigger and SendMessageToFlex widgets. Click on the widget and select your Assistant from the drop down. Click into the Messaging & Chat Config and change the ‘Send Message From’ field in the Messaging & Chat Config to {{trigger.message.ChannelAttributes.from}}.

                                      This ensures the correct channel address for the user — phone number, WhatsApp phone number or Facebook Messenger profile is available to Flex when the hand off takes place.

                                      Add the Split widget to check for hand-off

                                      This part is the same if you're using Flex or another contact center platform. Let’s recap how the send_to_agent task from step 3 works. It points to a function which inserts a JSON object in the Assistant memory using the remember action.

                                      remember = {
                                      "remember": { "sendToAgent": true }

                                      The Autopilot Studio widget in turn provides the memory payload to the Studio Flow when the Session ends, allowing you to build logic based off these variables. Drop the Split widget into the canvas. Click into the widget and in the Config tab, add widgets.{YOUR ASSISTANT WIDGET NAME}.memory.sendToAgent in the variable to test field. Click save.


                                      Next, switch to the Transitions tab and click the New Condition button and set it to true as shown below.


                                      Complete the hand-off

                                      With Flex

                                      If you’re using Flex, select the SendMessageToAgent widget as the next step to transition to. Add the memory payload in the Attributes text field in the Config tab, along with any channel-specific attributes you want to include. This attaches any information stored in your Assistant’s memory to the underlying Taskrouter task that Flex uses to route the conversation to the appropriate agent. To provide this information to a Flex agent, all you need to do is pull this data from the task and display it in the Flex agent UI. Learn more about TaskRouter for Flex here.


                                      The final state of your Studio Flow after adding and configuring all the widgets should look like this:


                                      Without Flex

                                      If you’re not using Flex, drop the HTTP Request widget into the canvas and point the transition on the Split widget to this widget.


                                      In the Config tab, set it up to make a POST request to the desired endpoint on your contact center platform and add the memory JSON to the request body. Your endpoint can then parse this payload to identify the last thing said by the user and any data collected by the Assistant.

                                      The final state of your Studio Flow should look like this:


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


                                      Using variables from the Autopilot Widget in Studio Flows

                                      Autopilot provides a number of different variables to the Studio Flow in addition to the bot memory. Learn more about these variables in How to use the Autopilot Studio Widget.

                                      7. Configure Messaging Channels

                                      To successfully hand-off messaging conversations from Autopilot to your Contact Center, the Studio Flow you're using needs to be configured with your messaging channels.

                                      With Flex

                                      If you’re using Flex, you just need to make sure the default WebChat and Messaging flows are configured properly. Go to Flex in the console, click into Messaging and make sure each channel is configured with the right studio flow as shown below. Learn more about Flex WebChat here.


                                      Without Flex

                                      If you’re not using Flex but are using Programmable Chat or a Twilio Messaging Channel, follow the instructions on configuring messaging channels using the Autopilot Studio widget from How to Build a Chatbot with Autopilot.

                                      That’s it! Congratulations, you’ve successfully built contextual agent hand-off from Autopilot to Flex.

                                      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.