Getting Started

This guide covers setting up and running Abot.

You'll learn:

• How to install Abot and connect your assistant to a database.
• How Abot thinks and processes messages.
• How to build a simple plugin for Abot.

But before we begin, it's pronounced Eh-Bot, like the Canadians, not uh-bot.

Guide assumptions

This guide is designed for developers that want to build a digital assistant from scratch. It does not assume any prior experience with Abot or A.I. or machine learning. Abot is a digital assistant framework built using the Go programming language. To learn Go, please read through some of the available resources:

• A Tour of Go
• The Little Go Book

If you at any time get stuck or need help with Abot, feel free to message abot-discussion@googlegroups.com and someone will help you right away.

What is Abot?

Abot is a digital assistant framework written in the Go programming language. It's designed to make it possible for anyone to build and customize digital assistants for themselves and for their businesses, whether that's a computer that answers phones and intelligently routes calls, schedules your business travel, or is just a better take on Siri that orders Ubers and does your laundry.

Abot exposes a simple HTTP API, so you can easily connect it to send, process, and respond to texts, emails, and more.

Downloading, installing and running an Abot server

Ensure you've installed Go and PostgreSQL is running, then open your terminal and type:

$ go get github.com/itsabot/abot
$ cd $GOPATH/src/github.com/your_username
$ abot new myProject
$ cd myProject
$ abot server

This will download Abot and set up your database. The port Abot runs on can be configured through the PORT environment variable in your ~/.bashrc or ~/.bash_profile or in abot.env in your project directory.

Communicating with Abot

To communicate with Abot locally, talk to her using abot console. But to communicate with Abot, we'll first need to sign up. Go to http://localhost:4200 and click Sign up in the header. Fill in appropriate information, and remember the phone number you use (which should be in the format of +13105555555 -- no spaces with a leading +1).

After you've created a user account, in another terminal (ensure abot server is still running), type:

$ abot console
> Hi
Hi there. :)

Replace the phone number above with the number you used for Sign Up to connect to the console. If you're running Abot on a remote server, you can also use the console to communicate remotely by passing in a web address or IP:

$ abot console https://your-abot-endpoint.com +13105555555
> Hi
Hi there. :)

You should see Abot's response! Alternatively, you can also communicate using curl.

$ curl -H "Content-Type: application/json" -X POST -d '{"CMD":"hi","FlexID":"+13105555555","FlexIDType":2}' http://localhost:4200

Abot won't do much at this point--we'll add plugins to add functionality. In the next 40 minutes, you'll learn how to customize these commands, integrate with SMS, and create your own.

Understanding how Abot works

Abot's core consists of three parts:

1. An API that accepts natural language inputs.
2. A state machine that tracks grammar and context across inputs, enabling the chaining of commands.
3. A router that selects the appropriate plugins to send the input based on the current command and past context.

It combines those three parts with tools and libraries designed to make programming a digital assistant as quick and fun as possible.

For every message Abot receives, Abot processes, routes, and responds to the message. Actually deciding what to say is the role of plugins. Let's take a look at an example:

1. User sends a message via the console, SMS, email, etc.: Show me Indian restaurants nearby.

2. Abot pre-processes the message, breaking the message into key components:

• Commands: [Show]
• Objects: [me, Indian restaurants nearby]

Abot can detect Commands, Objects, People, and Times out of the box.

3. Abot routes the message to the correct plugin:

• Route: show_indian
• Plugin: restaurant

4. The plugin generates a response: Sure, how does Newab of India sound? It's nearby.

5. Abot sends the response to the user.

Abot sends the response through the same channel the user chose, so if the user sends Abot a text, Abot will respond in text automatically. Thus, every message goes from User -> Abot -> Plugin -> Abot -> User.

Installing plugins

When Abot boots, it starts every plugin listed in your plugins.json file.

Open up plugins.json in your text editor of choice, and add to the Dependencies, so it looks like:

{
    "Dependencies": {
        "github.com/itsabot/plugin_weather": "*"
    }
}

Then in your terminal run:

$ abot install
Fetching 1 plugins...
Installing plugins...
Success!
$ abot server

And from another terminal:

$ abot console
> What's the weather like in LA?
It's 72 and sunny in LA.

Your first plugin

Abot provides all the tools you need to quickly and easily write these plugins through its shared library, which we'll learn about below.

Let's take a look at a "Hello World" plugin, which will introduce you to the plugin API. Let's download the plugin by adding it to our plugins.json and installing it like so:

$ tail $GOPATH/src/github.com/itsabot/abot/plugins.json
{
	...
	"Dependencies": {
		"github.com/itsabot/plugin_hello": "*"
	}
}

$ abot install
Fetching 1 plugin...
Installing plugin...
Success!

Now let's take a look at the contents of the plugin: https://github.com/itsabot/plugin_hello/hello.go. Pay close attention to the inline comments, which explain each piece of the plugin API as its introduced.

You can find and edit this file locally at $GOPATH/src/github.com/itsabot/plugin_hello. To build your own plugins and extend what Abot can do, please read the Building a Plugin guide.

You should see Abot boot with a line or two mentioning our new plugin, Hello World. Let's test it out. Open another terminal while abot server is still running, and type (using the same phone number with which you used to sign up at http://localhost:4200):

$ abot console
> Say hi
Hello World!

Abot just routed your message to the plugin based on the trigger defined in our abot_hello.go. The state machine told it to respond with "Hello World!" when it entered its first state, and since there were no other states, that state is replayed every time a new message matching our trigger is sent to Abot.

Deploying your Abot

To make Abot available to the outside world, we'll have deploy it to a server. Eventually https://www.itsabot.org will offer easy deployment (see the roadmap) but for now we'll deploy our Abot on Heroku to keep things simple. Go and Abot do make it easy to deploy on any web server, though.

To learn about deploying a Go project on Heroku, first familiarize yourself with this tutorial from Heroku: Getting Started with Go on Heroku. Once you have a grasp of what we're doing, open a terminal and run:

$ echo 'web: abot server' > Procfile
$ heroku create --buildpack https://github.com/itsabot/heroku-buildpack-go
$ heroku addons:create heroku-postgresql:hobby-dev --version 9.5
$ cat db/migrations/up/*.sql | heroku pg:psql
$ cat data/cities.csv | heroku pg:psql -c "COPY cities(name, countrycode) FROM stdin DELIMITER ',' CSV;"
$ heroku config:add ABOT_ENV=production \
ABOT_URL="https://YOURURL" \
ABOT_SECRET=$(LC_CTYPE=C tr -dc _A-Za-z0-9 < /dev/urandom | head -c 64) \
ABOT_DATABASE_URL=$(heroku config:get DATABASE_URL) \
ABOT_PATH="/app"
$ git push heroku master
$ heroku ps:scale web=1
$ heroku open

Be sure to replace YOURURL above with a user-presentable URL. If everything booted correctly, you'll see the "Welcome to Abot!" screen. If not, you can track down any issues with heroku logs --tail.

Once you see the Welcome screen, let's try communicating with our Abot. Sign up for an account using the web interface, then:

$ abot console https://yourapp.herokuapp.com +yourphone
> Hi
Hello there!

Replace yourapp and yourphone with the appropriate values, and you should see Abot respond to your message!

Configuring SMS

Abot makes it easy to add support for multiple communication tools, including SMS, phone, email, Slack, etc. In this guide, we'll learn how to set up SMS, so we can communicate with this new digital assistant via text messages.

First we'll need an SMS provider. We'll use Twilio since we've already written a driver for that, but you can use any provider in the same way as here by fulfilling the interface defined in itsabot/abot/shared/interface/sms/driver

Sign up for Twilio here: https://www.twilio.com. Take note of your assigned account SID, auth token, and Twilio phone number. You'll want to set the following environment variables in your Abot admin dashboard.

Now we'll add the Twilio driver, exactly like we added our Hello World plugin before. We'll want to add this line to our plugins.json:

{
    "Dependencies": {
        "github.com/itsabot/plugin_weather": "*",
        "github.com/itsabot/twilio": "*"
    }
}

Then run abot install to install the plugin. By adding that dependency, itsabot/twilio will automatically add a special POST /twilio route to Abot when we run abot install.

Let's also make sure that Twilio knows how to communicate with our app. Configure your Twilio account to POST to that route every time Twilio receives a message. To do that, go to https://www.twilio.com/user/account/messaging/phone-numbers and modify Request URL to be your-url.com/twilio set to HTTP POST.

Now with Abot running, go to your Abot admin dashboard (defaults to http://localhost:4200), sign in, and click on Settings in the left sidebar, and modify the following Twilio settings:

TWILIO_ACCOUNT_SID
TWILIO_AUTH_TOKEN
TWILIO_PHONE

Be sure your TWILIO_PHONE is in the form of +13105551234. The leading plus symbol is required.

We'll also want to update our environment variables on Heroku, so perform the same process on your Heroku instance.

Testing out Abot

To try Abot, let's first create an Abot account. Go to the site (heroku open) and click on Sign Up in the header at the top right. When entering your phone number, be sure to enter it in the format of +13105551234, or Twilio will reject it.

Once you've signed up, send Abot a text at your TWILIO_PHONE number from before:

Say hi

Sometimes responses via Twilio take a few seconds, but you should get a reply back soon,

Hi there :)

Next steps

As next steps, try:

• Building a Plugin
• Understanding the CLI
• Learning How to Contribute
• Seeing what's on our Roadmap