Menu

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

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 Assistant with a pre-built template using the Autopilot Command Line Interface (CLI).
  • Modify the Assistant to work with your Twilio account.
  • Use the Autopilot Studio Widget to add the Assistant to a Studio flow.
  • Implement simple logic in the Studio flow to facilitate agent handoff.
  • Deploy the Assistant 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 Assistant 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

You can learn more about the different commands supported by the CLI here.

2. Create an Assistant

In this guide, we’ll be creating an Assistant 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 Assistant in your account from a template.

Autopilot CLI.png

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

Assistant list.png

3. Modify the Assistant Behavior

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

Tasks

The Assistant template comes with five built-in tasks.

Task List.png

welcome_message

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.

get_flight_time

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 simple 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):

        flight-details.png

        send_to_agent

        This task is essential to building hand-off to Flex or any other customer service 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 once they’ve finished executing.

              
              
              
              

              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 Assistant 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 Assistant’s memory to indicate that the conversation needs to be handed off to an agent. Autopilot provides the current memory of the Assistant 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 us to parse this variable to execute the hand-off. We’ll cover this in Step 5.

                    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

                    book_flight

                    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 Assistant 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 Assistant 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:

                                book-flight-confirmation.png

                                change_flight

                                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 Assistant's behavior in three different situations:

                                      • Assistant Initiation: the Assistant 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.png

                                      Defaults should point either to:

                                      • An existing task. With our airline reservation Assistant, the Assistant Initiation default points to the welcome_message task.
                                      • A publicly accessible URL that responds with Actions. With our Assistant, the fallback points to a Twilio Function.

                                      Learn more about Defaults in the documentation.

                                      Stylesheets

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

                                      Learn more about Stylesheets in the documentation.

                                      stylesheets.png

                                      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 Assistant 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.

                                      book flight samples.png

                                      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 Model.png

                                      Next, navigate to the Logs tab to build a new model to add the training data you just provided to the Assistant’s machine learning model. You need to have built at least one model before you can start using your Assistant. When you make changes to your training data, like adding and deleting samples and fields, remember to build a new model each time for these changes to take effect.

                                      build model 2.png

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

                                      6. Build Agent Hand-off

                                      Now that you have trained and programmed the Assistant, 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 follow is different depending on whether you 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 red 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 Assistant you want to use from the drop down.

                                      config_assistant_1.png

                                      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.

                                      chat_config_2.png

                                      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

                                      webchat_config_flex.png

                                      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

                                      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.

                                      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.

                                      split1.png

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

                                      split2.png

                                      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.

                                      hand_off_flex.png

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

                                      flex_final_studio_flow.png

                                      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.

                                      hand_off_no_flex.png

                                      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:

                                      final_studio_no_flex.png

                                      Using variables from the Autopilot Widget in Studio Flows

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

                                      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.

                                      flex_messaging_config.png

                                      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.