otto-bot 0.0.3

Description:

ottobot 0.0.3

otto-bot
otto-bot is a helper utility for deploying chatbots using Twilio's Autopilot. With otto-bot you can configure your
chatbots locally and on deployment all of the API calls to setup the bot are handled for you. While I know Twilio has
its own CLI utility, the primary motivation for this library was to help me learn more about Autopilot and how to deploy
packages to PyPi. otto-bot is the outcome of that learning experience that I hope others may find beneficial as
well!
The library won't handle all features of building an Autopilot bot. For instance, there is not an API (at least that I
know of) for deploying custom Twilio Runtime Functions, so those will have to be deployed via the Twilio Console. I'm
going to try to keep up with changes to the Twilio API, changes in the API could impact performance. While working
through this project I identified a bunch of cool features to add-on that I'm planning on, so look forward to some
future updates!
Getting Started
To use otto-bot you must have a Twilio account with your Twilio account credentials setup as environmental
variables. You can find information about signing up for Twilio here
and setting up your environmental variables here.
Once you have your Twilio account setup, otto-bot can be installed via pip:
pip install otto-bot

otto-bot is only configured to work with Python 3.6 and above. If you have both a Python 2 and Python 3 version
installed you might need to run the command above using pip3 instead of pip.
Now you're ready to go!
Configuring your Chatbot
The core of otto-bot is the JSON file defining your chatbot. The content of your input file will instruct otto-bot
how to deploy your bot to Twilio. To get started you started there is an init command that will generate an empty
JSON file with placeholders for some of the more common elements your chatbot might use.
otto-bot init

By default the init command will include a placeholder for model, field type, task, and model build elements. These
basic settings are enough to get you started with building your chatbot. How you structure your JSON is influenced by
the Twilio API model itself, so I've included links for where you can get more information about each setting as well as
more advanced settings you can add to the JSON file.
Basic Settings- assistant
Each bot is defined by a single assistant object. The assistant object is required for each bot as it is the core
object all the other components will be linked to to create the bot. The assistant object contains metadata about your
bot and some of the default behaviors.
{
"assistant": {
"unique_name": "", # Required. A name to uniquely identify your bot.
"friendly_name": "", # Optional. A more descriptive name defining the bot.
"defaults": { # Optional. Assigns default actions.
"defaults": {
"assistant_initiation": "", # Only used in voice messages to provide a greeting for inbound messages.
"fallback": "", # How to respond if input can't be routed to a task.
"collect": {
"validate_on_failure": "" # What to do if there is an error collecting user input.
}
}
}
}
}

Extra information about settings for the Assistant settings can be found in the Twilio Assistant Resource
Basic Settings- field_type
As a part of your chatbot you can define custom fields that are extracted from the user's input. A chatbot does not
require you to include a field_type, but a chatbot can include multiple different custom field_types.
In the configuration file each field_type is defined with a prefix "field_type__" and must be uniquely named. An
example definition is below:
{
"field_type__your_custom_field": {
"unique_name": "", # Required. Unique name identifying your custom field type.
"friendly_name": "", # Optional. A more descriptive name defining the field type.
"values": [] # Required. A list of values defining the field.
}
}

You can find further details about this settings here: Twilio FieldType Resource
Basic Settings- tasks
Tasks are the core of what dictates how your chatbot will interact with messages. Your chatbot must contain at least
one task. In the JSON file each a task is defined with the "task__" prefix and contains the following information:
{
"task__your_task": {
"unique_name": "", # Required. Unique name identifying the task.
"friendly_name": "", # Optional. Most descriptive name defining the task.
"actions": { # Required. A list of actions your task should take.
"actions": []
},
"task_fields": [ # Optional. If your task uses custom fields you must define them here.
{
"unique_name": "", # Required. Unique name identifying the field for the task.
"field_type": "" # Required. Field type to assign to the field. Could be custom, or a Twilio default field.
}
],
"samples": [] # Required. List of key phrases that will trigger this task.
}
}

More details about these settings and additional settings are here: Twilio Task Resource.
Basic Settings- model
The last component of the JSON file is the "model". The most build component tells Twilio to build the actual model
using everything defined in the rest of the JSON file.
{
"model": {
"unique_name": "" # Required. Unique name to identify the model.
}
}

See here for extra details: Twilio ModelBuild Resource.
Deploying your Chatbot
Once you've defined your chatbot in the JSON file you can deploy the chatbot to Twilio with the following:
otto-bot deploy chatbot-config.json [--overwrite]

The deploy command reads the configuration JSON and will make all the API calls that are required. By default
otto-bot will deploy the bot exactly as defined in your JSON. If you have a chatbot that already exists all associated
resources with the chatbot will be deleted and replaced with the resources currently defined in the JSON file. You can
use the --overwrite option to automatically overwrite an existing bot. Otherwise you will be prompted during
deployment to agree to overwrite the existing bot.
Before deploying the bot a number of validation checks are run on the input file to ensure there are no errors. These
checks ensure that your bot will successfully deploy without an error before anything starts to get deleted. In
addition to doing the error checking alerts will be raised about best practices that aren't necessarily errors, but
that could help improve your bot. These checks will capture many common errors, but are not entirely robust. As new
errors are discovered I'll keep these validation checks up-to-date.
Deployment Limitations
otto-bot handles a lot, but not all aspects of your bot's deployment. Twilio currently does not have an API for
deploying custom Runtime functions. If you want to include a custom Runtime function with your bot you will need
to define that function through the Twilio console.
A second limitation is that once your bot is deployed you will have to go into the Twilio console and attach your
bot to the channel you would like to deploy to.
Deleting a Chatbot
So, you've deployed a chatbot and don't want to use it anymore, the teardown command will delete your bot and all
the resources associated with it.
otto-bot teardown unique_name

You can call the teardown command along with the unique_name of the bot you want to delete and your bot will be
deleted.
Getting Started- Examples
In the examples directory there is a worked
example using the Twilio Deep Table Autopilot Tutorial
, demonstrating how otto-bot can be utilized.
What's Next
I've learned a lot about Twilio Autopilot through this process. From this process there are a number of initial
enhancements I want to add. If there is any other functionality you'd like to see let me know and I'll make sure it
gets added!