How to build a chatbot
Twilio Autopilot does not officially support the Conversations API as a channel.
This guide will give you the resources and information you need to build a chatbot with Autopilot.
With Autopilot, you can build AI chatbots powered by machine learning to help your users interact with your application through natural conversations. Autopilot uses a task-driven programming model where tasks correspond to outcomes the user wants from interacting with your bot, like booking an appointment 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 chatbot can be trained to recognize different possible phrases and words the user could say that correspond to a task.
Instead of requiring your users to provide exact responses or keywords to interact with your bot, the chatbot 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 bot template from the Twilio Console.
- Modify the bot to work with your Twilio account.
- Program and train the bot to perform some new tasks.
- Deploy the bot on messaging channels supported by Twilio - Programmable Chat, SMS, WhatsApp, and Facebook Messenger.
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
Let’s review how the bot you just created from the template is set up.
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 thewelcome_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 three 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
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. 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.
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?
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.
Next, deploy the bot on a messaging channel.
8. Configure Messaging Channels
Autopilot’s omni-channel capabilities allow you to deploy your bot to the messaging channel of your choice without writing additional code for each channel. There are two ways you can do this — directly configuring your bot with the messaging channel or using the Autopilot Studio Widget.
If you’re using one or more messaging channels through Flex, you should use the Autopilot Studio Widget to connect messaging channels to your bot. Refer to the guide How to hand-off messaging conversations from Autopilot to your Contact Center for how to do that.
Programmable Chat
Direct Configuration
- Go to the Channels page in the navigation menu in the console.
- Select Programmable Chat.
- Copy the Chat URL automatically generated for your bot. This URL is unique to each bot.
- Conversations in Programmable Chat take place within channels. The Programmable Chat API allows you to set a webhook on each channel to be notified of new activity within the channel. Configure the Chat URL copied in step 3 as the webhook URL on the channels you want your bot to join.
POST /Services/ISXXX/Channels/CHXXX/Webhooks/
request parameters
Attribute |
Value |
Type |
webhook |
Configuration.Url |
{Your Autopilot Programmable Chat URL} |
Configuration.Method |
POST |
Configuration.Filters |
onMessageSent |
Example API Request
curl -X POST 'https://chat.twilio.com/v2/Services/{ChatServiceSid}/Channels/{ChannelSid}/Webhooks/' \
-d "Type=webhook" \
-d "Configuration.Url={ProgrammableChatURL}" \
-d "Configuration.Method=POST" \
-d "Configuration.Filters=onMessageSent" \
-u {AccountSid}:{token}
Make sure to replace:
{ChatServiceSid} - with the Chat Service Instance Sid you are using
{ChannelSid} - with the Channel you created for the user
{AccountSid} - with the Account Sid
{Assistant Sid} - with the Autopilot Assistant Sid
{ProgrammableChatURL} - with your Assistant's Programmable Chat URL (Channels -> Programmable Chat in Console)
You can also learn more about configuring Programmable Chat in the documentation.
Studio Widget
- Copy the Flow SID of the Studio flow that contains your Autopilot Studio Widget.
- Similar to step 4 in the Direct Configuration approach, configure the webhook on each channel to point to the Studio flow so that your bot can receive new messages.
POST /Services/ISXXX/Channels/CHXXX/Webhooks/
request parameters
Attribute |
Value |
Type |
studio |
Configuration.FlowSid |
|
Example API Request
curl -X POST 'https://chat.twilio.com/v2/Services/{ChatServiceSid}/Channels/{ChannelSid}/Webhooks/' \
-d "Type=studio" \
-d "Configuration.FlowSid={FlowSid}" \
-u {AccountSid}:{token}
Make sure to replace:
{ChatServiceSid} - with the Chat Service Instance Sid you are using
{ChannelSid} - with the Channel you created for the user
{AccountSid} - with the Account Sid
{Assistant Sid} - with the Autopilot Assistant Sid
{Flow Sid} - with the Studio Flow Sid
New messages posted in the Chat Channel will create a new Studio Execution, enabling the Studio Flow to interact with the Chat user.
SMS
Direct Configuration
- Go to the Channels page in the navigation menu in the console.
- Select Programmable Messaging.
- Copy the Messaging URL automatically generated for your bot. This URL is unique to each bot.
- Go to the Phone Numbers page in the console and select the phone number you want to use, or buy a new one.
- In the configuration menu for the phone number, under Messaging, select Webhook for ‘A Message Comes In’ and paste the URL you just copied.
- Start testing your bot!
Studio Widget
(Refer to the Hand-off messaging conversations from Autopilot to your Contact Center guide for step-by-step instructions on using Autopilot in Studio)
- Open the Studio flow containing your Autopilot bot.
- Click on the Trigger widget and copy the Webhook URL.
- Similar to step 4 in the Direct Configuration approach above, navigate to the phone numbers page and paste the Webhook URL. Alternatively, you can select Studio Flow in the drop down instead of Webhook and select the right flow
- Start testing your bot!
The process for deploying your bot on WhatsApp is nearly identical to the one for SMS, with the only difference being that instead of pointing the Messaging URL or Studio Webhook to an SMS-enabled phone number, you need to point them to your WhatsApp Sender.
Learn how to use WhatsApp with Autopilot here.
Facebook Messenger
The process for deploying your bot on Facebook Messenger is nearly identical to the one for SMS, with the only difference being that instead of pointing the Messaging URL or Studio Webhook to an SMS-enabled phone number, you need to point them to the Facebook Messenger Channel you’ve configured in the Twilio Console.
Learn how to use Facebook Messenger with Autopilot here.
Keep Building!
- Add some more tasks, like a post-stay customer satisfaction survey.
- Learn how to build contextual hand-off to a live agent.
- Learn how to train bots in production.
- Understand how Task Confidence works.
- Explore the Autopilot documentation.
- Get familiar with the Autopilot CLI.
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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.