Build the future of communications.
Start building for free

Build your own holiday text adventure with Twilio Autopilot

Holiday text adventure

Did you ever play any classic text adventure games like Zork or Colossal Cave Adventure?

Ever since I starting coding, I’ve wondered how those developers built those games. How do you account for all the different phrases a player might try to say? My guess: back in the 80s and 90s they did it largely through long, exhaustive lists of potential phrases.

So in October when we launched Twilio Autopilot to beta I knew exactly what to build first: my very own text adventure game.

Turns out we only need about a dozen lines of JSON to pull it off. Ready? Let's get started.

What’s Twilio Autopilot?

Twilio Autopilot allows you to build intelligent bots using natural language understanding and machine learning.

It’s a perfect fit for a text adventure because we can define as few as ten phrases for an individual action (e.g. “open the door”) and Autopilot will be able to match hundreds of variations of that phrase to that action.

What really makes Autopilot special is its ability to hand off a conversation to a human. We didn’t design Autopilot to pass the Turing test — it uses machine learning for the parts of a conversation a bot can handle, and escalates to a human for the parts it can’t.

But don’t underestimate the power of Autopilot’s natural language understanding. In this post we’ll use the Autopilot console and a few lines of JSON to build a simple “escape the room” text adventure.

First, we'll need a free Twilio account.

Sign up for Twilio and create an Assistant

The first step in building our simple text adventure is to get a free Twilio account. Sign up for an account here if you don’t have one already, and then be sure to claim a Twilio phone number.

Buy a Twilio phone number

Next, we need to create an Autopilot Assistant. Assistants are how you use Autopilot to power conversations. We’ll load all our adventure content into our assistant and we’ll wire up our phone number to forward incoming text messages to our assistant as well.

Head over to the Autopilot section of the Twilio Console and click “Create a new Assistant.” Give your assistant a name like “text-adventure.”

Create a Twilio Autopilot assistant

Now we’re ready to start customizing our assistant.

Define our first task

Assistants have many Tasks. By default, our assistant comes with just one: a task called “hello_world.” You can see it in the “Task Builder” page for the assistant:

The "hello_world" assistant task

Tasks are where all the content of our assistant lives. Each task is a JSON object with a key called “actions” — that’s where we tell our assistant what to do when one of our users requests  this task.

There are a few different actions our assistant can perform within a task. The “say” action responds with text for SMS interactions or text-to-speech for phone calls or smart assistants. You can also use the “collect” action to gather input from your users (like details for a restaurant reservation) or the “remember” action to tell your assistant to store some metadata about this conversation.

For our simple text adventure we’ll only need the “say” action, though. Edit the say action in our hello_world task so it says “Hello, world!” and click save.

Editing the "hello world" assistant task

Now we’ve got our first task ready to go, but we’ll need to wire up our assistant to our phone number before we can try it out.

Configure our Twilio phone number

To connect our assistant to our Twilio phone number, start in the “Channels” page for our assistant. Then click on the icon for “Programmable SMS” and copy the “Messaging URL” provided on that page.

Our assistant's messaging URL

Head back to the phone numbers section of the Twilio Console and click on the phone number you added earlier. Scroll down to the “Messaging” section and paste your assistant’s messaging channel URL in the “A message comes in” field. Then click “Save.”

Configuring our Twilio phone number

Now you’re ready to test it out! Try sending any text message (like “Hi!”) to your Twilio phone number. You should get a reply a few seconds later which says “Hello, world!”.

Build our adventure

With our assistant up and running, it’s time to start building our adventure.

For this simple adventure we’ll use an “escape the room” premise. The first couple tasks will lead the player to a room and set up a small puzzle. The player will then examine a few different items in the room and, hopefully, discover the answer to the puzzle.

In our adventure the player will join me at Twilio HQ as I prepare to attend the SF Python meetup group’s holiday party. I’ll spill some hot chocolate on myself (not my first snack-cident at work) and the player will be free to explore the office’s kitchen while I try to clean up. Eventually the player will find a stack of TwilioQuest t-shirts. The solution to the puzzle is to give me one of those shirts so I can wear it to the party, ending the adventure.

Let’s begin by updating our “hello_world” task to set the scene for our adventure.

A whole new world

Go back to the task builder for our assistant and open up the definition for the “hello_world” task. Instead of saying “Hello, world!” let’s use this longer “say” value to set the scene for our adventure:

  "say": "You walk up to Twilio's office building. All the lights are still on but nobody seems to be around - except for Andrew, who you spot in the lobby waiting for you.\n\n\"Come on in! So glad you could make it!\" he says, ushering you into the elevator and up to Twilio's offices.\n\n\"I'm so glad you saw my tweet about an extra ticket to the SF Python holiday party. Are you excited?\""

Be sure to include the backslashes to escape the quotations within our text and the “\n” characters to separate our content into a few different paragraphs when viewed over SMS.

We need to make one more tweak to this task to support our adventure. Because we expect the player to continue their conversation with our assistant after it sends this message, we need to add a “listen” action underneath our “say” action.

The first part of our adventure

Click “Save” and we’ve got the beginnings of an adventure.

Add a second task

Now let’s add another task for when the player answers our question with a “yes”. Click the “+” icon at the top of the task list and give the new task a name like “excited_yes.”

We’ll use this “say” value for when a player expresses excitement about attending the SF Python holiday party with me:

  "say": "\"Who wouldn't be?\" he says.\n\nYou two exit the elevator and head for Twilio's kitchen. \"Need a snack before we head out? I was about to make some hot chocolate myself, if I can get this dang packet open.\"\n\nBefore you can answer, a tragedy unfolds in slow motion in front of you: after struggling to open the packet of hot chocolate powder, Andrew rips it completely in half and knocks over the mug of hot water next to him in the process. When the dust settles you see his shirt's covered in half-made hot chocolate.\n\n\"SON OF A...\" he says, before regaining his composure. \"Ugh, I can't go to the party like this. Can you look around for something else I can wear while I clean this up?\"\n\nSay 'look around' to survey the kitchen."

Be sure to include the “listen: true” action on this task and all others, except for the task which concludes the adventure (more on that later).

With two tasks defined in our assistant we’re well on our way to building a small world for our player to explore. But how will our assistant know which task the player is asking for at any given moment?

That’s where Samples come in.

Add some samples

Samples are how you help your assistant understand what a user might say when they’re asking for a task.

For example, if we were building an assistant for a restaurant and we had a task to make a new reservation, we might add samples like “make a reservation”, “reserve a table”, or “I need a table”. Autopilot uses those samples when building your models to make your assistant flexible to your user’s input. If your user says “I’m looking for a table for dinner,” there’s a good chance our assistant would understand that they want the reservation task and it would then respond with that task’s actions.

The “hello_world” task worked with any input in our last test because it was the only task in our assistant. Now let’s give that task some samples of what a user might actually say to start our adventure.

Click on the “Modify” link next to our “hello_world” task. Then click on “View samples.” Here’s where we’ll add a few samples of things a player might say when they want to start our adventure: begin, start, go, etc.

Adding samples for our first task

Your assistant will work best when every task has at least 10 samples. The more samples you can add for a task, however, the better your assistant will understand how users might ask for it.

Let’s now add some samples for our “excited_yes” task: yes, yeah, yup, of course, for sure, etc.

Adding samples for our second task

With two tasks and samples for each, the last thing we need to do is build a new version of our assistant’s natural language understanding model so we can bring it all together.

Build our first model

To build our assistant’s natural language understanding model, first visit the assistant’s “Natural Language Router” page. Next, click “Build models,” and then click “Create your first model build.”

Give your new model build a name like “v0.1” and then click “Create”:

Building our assistant's model

After a few seconds our new model will be ready for our assistant to use. Remember this page — we’ll need to build models whenever we change a task or anything else about our assistant.

Now try texting “begin” to our assistant. Then after the first response try texting in one of the samples for the “excited_yes” task. Now try texting a phrase that’s close to one of our samples but not an exact match — our assistant should still understand what you mean!

Finish building the adventure

To build out the rest of our adventure, take a look at the tasks and samples stored my autopilot-text-adventure repository on GitHub. Copy and paste each JSON file in that directory to a new task in our assistant, and copy and paste the contents of each .txt file to add samples for each task.

Note that the final task, called “give_shirt”, doesn’t have a “listen” action. That task concludes the adventure, so by omitting a “listen” action we’re telling Autopilot that we expect the conversation to end after the player uses that task.

Build your model one last time (you can call this one v0.2) and then you’ve got a bona fide text adventure on your hands!

Who wants to play video games?

Your adventure is just beginning

With just a dozen tasks and a little creativity we’ve created a fun quick text adventure using Twilio Autopilot. But what's next?

You can start by customizing the content within this adventure to make it your own — I bet you’d make a better sidekick to our protagonist than I did. Or, with just a few clicks you can play your adventure on a phone call with Twilio Programmable Voice. Alternatively, it’s only a little more effort to get your assistant connected to Alexa, Google Assistant, Facebook Messenger, or Slack.

Let us know if you build your own by sending us a tweet at @twilio and @andrewtorkbaker!

And then there’s the whole other half to Twilio Autopilot we didn’t touch on today: handing off a conversation to a human. Maybe we could build a more difficult adventure but let players ask the author for hints when they get stuck? Or even an adventure where the author customizes the ending for every player?

One thing’s for sure: I can’t wait to play what you build!

Andrew T. Baker is the Director of Developer Education at Twilio and really wants someone to build that bot-human hybrid text adventure so he can play it. He can be reached on Twitter @andrewtorkbaker or at

Sign up and start building
Not ready yet? Talk to an expert.