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?

Twilio Autopilot Ruby Quickstart

With Twilio's Autopilot, you can build messaging bots and virtual voice assistants powered by Ruby and Twilio's own Natural Language Processing engine.

In this quickstart, we're going to build a simple voice assistant that can tell a caller a joke if they ask for one.

Not a developer? Check out the console-only version of this quickstart!

Let's get started!

Show me how it's done

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

Buy a voice compatible number with Twilio

You’ll then see a list of available phone numbers and their capabilities. Find a number that suits your fancy 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 Ruby applications next.

Take me through the setup

If you’ve gone through one of our other Ruby Quickstarts already and have Ruby and the Twilio Ruby helper library installed, you can skip this step and get straight to creating your first assistant.

To build and manage your assistant with Ruby you'll need to have Ruby and the Twilio Ruby helper library installed.

Install Ruby

Please follow the following instructions if you are using Windows, Linux or MacOS.

Twilio’s Ruby SDK supports Ruby versions 2.2 and above. You can use any of these versions for this quickstart. To check if the installation was successfully complete, use this command:

ruby --version
ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-darwin17]

Install the Twilio Ruby Helper Library

The easiest way to install the library is using gem, a package manager for Ruby that makes it easier to install the libraries you need. Run this in the terminal:

gem install twilio-ruby
All set! Let's create that assistant now.

Create your virtual assistant

Now that you have Ruby and twilio-ruby 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.rb and type or paste in this code sample:


        You’ll need to edit this file a little more before you can create your assistant:

        Replace the placeholder credential values

        Swap the placeholder values for account_sid and auth_token with your Twilio credentials.

        Go to 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:

        Find your Account SID and Auth Token in the Twilio Console

        Open create_assistant.rb and replace the values for account_sid and 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:

        ruby create_assistant.rb

        Congratulations! You've just created your first virtual assistant with Ruby.

        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.

        Allow my Assistant to introduce itself

        Create and train your assistant's default task

        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.

        Your assistant doesn't have any tasks it knows how to do yet. We'll start by creating a simple task, hello-world, that says a brief greeting and listens for user input.

        Copy the following code sample into a file named create_hello_world.rb


              Once again, update the placeholders for account_sid and 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.rb code printed out – you can also find this value in the Autopilot section of the console.

              Save your changes and run this file:

              ruby create_hello_world.rb

              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.

              Show me how to train my assistant

              Add training samples

              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 'hello-world' task.

              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.rb, and add the following code sample:


                    Once again you'll need to update the account_sid, auth_token, and Assistant SID placeholder (UAXXXX....) to use your unique values.

                    Once you've provided your unique values, run this file

                    ruby train_hello_world.rb

                    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.

                    Set hello-world as your assistant's default task

                    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.rb and include the following code:


                          Swap out the account_sid, auth_token, and assistant SID values with your own, then run the file:

                          ruby set_default.rb

                          Now your assistant knows how to handle an incoming call. All you have left to do is build the training model.

                          Build your assistant's 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.rb 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 account_sid, auth_token, and the Assistant SID with your data. Then save the file and run it:

                                ruby build_training_model.rb

                                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.

                                Connect my Assistant to a phone number

                                Connect your assistant to your Twilio phone number

                                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:


                                Set the autopilot voice handler as the URL for your Twilio phone number

                                Replace <ACCOUNT_SID> and <ASSISTANT_SID> with your unique Account SID and the Assistant SID that your code printed out in the previous section.

                                Test it out

                                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.

                                Let's tell a joke

                                Create a second task that tells a 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.

                                Create a task that tells a joke

                                Make a new file called create_joke_task.rb and include the following code sample:


                                      Replace the placeholder values for account_sid, 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:

                                      ruby create_joke_task.rb

                                      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.

                                      Add training samples

                                      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.rb and include the following code:


                                            Again, update the account_sid, auth_token, and Assistant SID placeholder (UAXXXX....) to use your unique values.

                                            Save the file and run it to create your training samples:

                                            ruby create_joke_samples.rb

                                            You'll need to re-build the machine learning model for your assistant for these changes to take effect.

                                            Build the model

                                            You can create a new model build by opening up your build_training_model.rb file and update the unique_name value to 'v0.2' to properly version the machine learning models. Run the file:

                                            ruby build_training_model.rb

                                            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.

                                            Test your assistant with a query

                                            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.rb and include the following code:


                                                  Once you've swapped out the placeholder values with your unique account_sid, auth_token, and Assistant SID, run the code:

                                                  ruby test_query.rb

                                                  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!

                                                  What's next?

                                                  What's next?

                                                  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:

                                                  We can't wait to see what you build!

                                                  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.