Not a developer? Check out the console-only version of this quickstart!
Let's get started!
If you already have a Twilio account and a voice-enabled Twilio phone number, you’re all set here! Feel free to jump to the next step.
Before you can build a virtual assistant with Twilio, you'll need to sign up for a Twilio account or sign into your existing account. For this quickstart, you'll also need a Twilio phone number that's capable of making calls.
You can sign up for a free Twilio trial account here.
- When you sign up, you'll be asked to verify your personal phone number. This helps Twilio verify your identity and also allows you to make calls to your phone from your Twilio account while in trial mode.
- Once you verify your number, you'll be asked to create a project. For the sake of this tutorial, you can click on the "Learn and Explore" template. Give your project a name, or just click "skip remaining steps" to continue with the default.
- Once you get through the project creation flow, you'll arrive at your project dashboard in the Twilio Console. This is where you'll be able to access your Account SID, authentication token, find a Twilio phone number, and more.
If you don't currently own a Twilio phone number with Voice functionality, you'll need to purchase one. After navigating to the Buy a Number page, check the "Voice" box and click "Search."
You’ll then see a list of available phone numbers and their capabilities. Find a number that you like and click "Buy" to add it to your account.
Now that you have a Twilio account and a programmable phone number, you can start building your virtual assistant! To make building with Autopilot easier, we'll install Twilio's official helper for Python applications next.
If you’ve gone through one of our other Python Quickstarts already and have Python and the Twilio Python helper library installed, you can skip this step and get straight to creating your first assistant.
To build and manage your assistant with Python you'll need to have Python and the Twilio Python helper library installed.
If you’re using a Mac or Linux machine, you probably already have Python installed. You can check this by opening up a terminal and running the following command:
You should see something like:
$ python --version Python 3.4 # Python 2.7+ is okay too
Twilio’s Python SDK supports both Python 2 and Python 3. You can use either version for this quickstart, but we recommend using Python 3 for future projects with Twilio unless there are specific libraries your project needs which are only compatible with Python 2.
The easiest way to install the library is using pip, a package manager for Python that makes it easier to install the libraries you need. Run this in the terminal:
pip install twilio
If you get a
pip: command not found error, you can also use
easy_install by running this in your terminal:
If you'd prefer a manual installation, you can download the source code (ZIP) for
twilio-python and then install the library by running:
python setup.py install
in the folder containing the twilio-python library.
Now that you have Python and
twilio-python installed, you can spin up a new assistant with a single API request.
An Assistant is a conversational application or bot that you can deploy across multiple channels, like SMS and Voice. Each assistant is independent of other assistants you create and has a unique set of tasks that it can do.
Create and open a new file called
create_assistant.py and type or paste in this code sample:
You’ll need to edit this file a little more before you can create your assistant:
Swap the placeholder values for
auth_token with your Twilio credentials.
Go to https://www.twilio.com/console and log in. On this page, you’ll find your unique Account SID and Auth Token, which you’ll need any time you interact with the Autopilot API via the Twilio Client like this. You can reveal your auth token by clicking on the view link:
create_assistant.py and replace the values for
auth_token with your unique values.
Please note: it's okay to hardcode your credentials when getting started, but you should use environment variables to keep them secret before deploying to production. Check out how to set environment variables for more information.
Save your changes and run this script from your terminal:
Congratulations! You've just created your first virtual assistant with Python.
The last line in this code prints out the
Assistant SID to your command line terminal or shell. You may want to jot it down or copy it into a unique file – this value is what you'll use to add tasks and training samples to your assistant later on.
A Twilio Autopilot assistant runs on tasks.
A task is a set of actions your assistant needs to carry out when interacting with users. Tasks are modeled on something your end user wants or needs, and the specific things your assistant needs to do to help them out.
An assistant usually has many tasks that power it. These could be simple tasks like confirm or cancel or more complex tasks like make-a-reservation.
Actions instruct the assistant on how to perform a given task.
When an assistant executes a task, it will run through all specified actions and then end the interaction. Most assistants will have many tasks that each contain multiple actions. You can imagine a virtual assistant that says something, listens for input, collects some data, and then hands off the caller to an agent.
Copy the following code sample into a file named
Once again, update the placeholders for
auth_token to use your unique values.
You will also need to replace the placeholder value for the Assistant SID,
UAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX, with the distinct SID for your new assistant. This is the SID value that our
create_assistant.py code printed out – you can also find this value in the Autopilot section of the console.
Save your changes and run this file:
You've just created your assistant's first task! Before it's ready to go though, we need to add some training samples to the task and set it as our assistant's default task. Let's do that next.
Now we need to train our assistant to listen for key words and phrases that show that our caller wants to hear a joke. To do this, we'll add some samples to this new task so that our assistant can distinguish it from the '
A sample is the training data your assistant uses to understand your users' input. Samples define how people might describe a task when speaking or typing, and are necessary for your assistant to learn how to interact with your users.
Create a new file,
train_hello_world.py, and add the following code sample:
Once again you'll need to update the
auth_token, and Assistant SID placeholder (
UAXXXX....) to use your unique values.
Once you've provided your unique values, run this file
You've just given your assistant some training data for this task!
Usually it's best to provide at least ten samples for any given task so that your assistant can map human input to the task. However, our hello-world task will serve a special purpose for our assistant: we'll set this task as the assistant's default tasks so that your assistant will say this phrase when anyone calls in. Because your assistant will use this task before a user starts interacting with it, it's okay to just have a few samples.
Every assistant has a default parameter that specifies:
- initiation actions, or the task it executes when someone calls and you want your assistant to begin the interaction
- fallback, or the task that the assistant uses when it does not understand a human's input
To set your hello-world task as your assistant's defaults, create a new file named
set_default.py and include the following code:
Swap out the
assistant SID values with your own, then run the file:
Now your assistant knows how to handle an incoming call. All you have left to do is build the training model.
Before your assistant can leverage the samples we just created, you'll need to create a
Model Build. Creating a new Model Build will incorporate these changes into the machine learning model that powers your assistant.
Create a new file named
build_training_model.py and include the following code:
This code will kick off a Model Build for your assistant.
Any time you create new Tasks or add a new set of Samples to your assistant, you should create a Model Build to train a new model using your data. Note that we've included the optional parameter
unique_name in this code. While not required, this helps us keep track of our machine learning model as we add tasks, samples, and other data to our Assistant.
Make sure you've replaced the placeholder values for
auth_token, and the
Assistant SID with your data. Then save the file and run it:
To test that you've given your assistant an inital task and trained the machine learning model, you're ready to connect it to your Voice-enabled Twilio Phone number. Let's learn how to do that next.
While you can deploy your Autopilot-powered assistant to any number of channels including SMS, Slack, and Alexa, we'll start by deploying our new assistant to a voice-enabled Twilio phone number so that we can call this assistant to test it out:
Go to your Phone Numbers page in the Twilio Console.
Select the phone number you own that you'd like to connect to this assistant.
Scroll down to the Voice & Fax Configuration section.
Next to "A call comes in," select Webhook from the drop-down. In the text field, enter the following:
<ASSISTANT_SID> with your unique Account SID and the Assistant SID that your code printed out in the previous section.
Now you can call the Twilio phone number you just updated and hear your assistant say "Hi there, I'm your virtual assistant! How can I help you?" However, if you ask your assistant for anything it will just repeat this message. It's time to add some more functionality to your assistant by teaching it how to tell a brief joke on-demand.
Most of the time we'll want an assistant that can handle more than one type of interaction. So far our assistant is polite, but can it answer a question?
We'll have our assistant handle one inquiry to start: "tell me a joke." Let's add a new task to our assistant by creating a "tell-a-joke" task with several training samples.
Make a new file called
create_joke_task.py and include the following code sample:
Replace the placeholder values for
auth_token, and the Assistant SID (
UAXXXX...) with your unique values.
Save the file and run it to add this new task to your assistant:
Make note of the printed output – this is the unique SID for your new Task, you'll need it when you add samples to train your assistant next.
Just as you did with the
hello-world task, you'll need to add training samples to this new
tell-a-joke task. Since your assistant needs to map human speech to this task, we'll make sure to give it the bare minimum of ten samples (and you can always add more).
Create a new file called
create_joke_samples.py and include the following code:
Again, update the
auth_token, and Assistant SID placeholder (
UAXXXX....) to use your unique values.
Save the file and run it to create your training samples:
You'll need to re-build the machine learning model for your assistant for these changes to take effect.
You can create a new model build by opening up your
build_training_model.py file and update the
unique_name value to '
v0.2' to properly version the machine learning models. Run the file:
At this point, your assistant is ready to tell a joke on demand!
Before you test it out by giving it a ring, let's take a quick look at how we can programmatically query the natural language understanding of this assistant.
Twilio Autopilot's Query API resource is the endpoint where Autopilot's natural language understanding analysis is performed. You can leverage this endpoint to check that your assistant correctly routes a phrase or word to the appropriate task.
Create a file named
test_query.py and include the following code:
Once you've swapped out the placeholder values with your unique
Assistant SID, run the code:
This code will print the name of the task your query triggered – you should see "
tell-a-joke" printed to your command line.
Now you can call your assistant to test it out! Call the Twilio phone number you connected to this assistant.
You should hear your new greeting. Ask your assistant to tell you a joke however you like: you should hear your joke read back to you!
Congratulations, you just built your first Twilio assistant with Autopilot!
This quickstart taught you the basics of building a simple Autopilot-powered assistant, but Autopilot also powers bots and virtual assistants that can collect data and route users through complex flows.
Go deeper with Twilio Autopilot with the following tutorials and reference docs:
- Learn how to make a more complex assistant that can gather and track user input in our Deep Table Reservations tutorial.
- Learn how to deploy your assistant to multiple channels, including SMS, Alexa, or Slack.
- We leveraged Autopilot's say and listen actions in this quickstart, but there's a lot more Autopilot can do! Learn about the other available actions here.
- Explore the full set of API reference documentation for Twilio Autopilot.
We can't wait to see what you build!