# Alice [![Hex Version](]( [![Deps Status](]( [![Hex Downloads](]( [![License: MIT](](

#### A Lita-inspired Slack bot written in Elixir.

<img height="135" src="" align="left" />

_The Caterpillar and Alice looked at each other for some time in silence: at last the Caterpillar took the hookah out of its mouth, and addressed her in a languid, sleepy voice._

_"Who are YOU?" said the Caterpillar. This was not an encouraging opening for conversation. Alice replied, rather shyly, "I—I hardly know, sir, just at present—at least I know who I WAS when I got up this morning, but I think I must have been changed several times since then."_

__Anyone running Alice 0.3 or higher is highly encouraged to move to [0.3.6] ASAP. Version [0.3.6] will save the state data in Redis as JSON, whereas the previous versions were simply converting the elixir into a string. This had some limitations, namely only supporting 50 key-value pairs before producing an unparsable string with a "..." in it. Version [0.3.6] will also migrate your existing state to use JSON, so there’s no going back after upgrading. This change should not affect handler so it is not a breaking change.__

For an example bot, see the [Active Alice] bot. For an example
handler, see [Google Images Handler].

You'll need a Slack API token which can be retrieved from the [Web API page] or
by creating a new [bot integration].

[wiki page]:
[Active Alice]:
[Google Images Handler]:

[Web API page]:
[bot integration]:

## Handler Plugins

Alice has a plug in system that allows you to customize the functionality of
your bot instance. See [the docs] for more information about creating your own

[the docs]:

### Known Handlers

* Alice Against Humanity: [hex](, [code](
* Alice Google Images: [hex](, [code](
* Alice Karma: [hex](, [code](
* Alice Reddit: [hex](, [code](
* Alice Shizzle: [hex](, [code](
* Alice XKCD: [hex](, [code](
* Alice Doge [hex](, [code](

If you write your own handler, please submit a pull request and update this list!

## Creating Your Own Bot With Alice

### Create the Project

Create a new mix project.
mix new my_bot
cd my_bot
rm lib/my_bot.ex test/my_bot_test.exs

### Configure the Application

In `mix.exs`, bring in alice and any other handlers you want. You also need to
include the `websocket_client` dependency because it's not a [hex] package.
defp deps do
    {:alice,                  "~> 0.4.0"},
    {:alice_against_humanity, "~> 0.1.0"},
    {:alice_google_images,    "~> 0.1.0"}

In the same file, configure the app, registering any handlers you want. You can
add handlers through dependencies, or you can write them directly in your bot
instance. (See [Writing Route Handlers] for information on how to write a
handler. We recommend putting them in `lib/alice/handlers/`.)

[Writing Route Handlers]:

def application do
  [ applications: [:alice],
    mod: {
      Alice, %{
        handlers: [

In `config/config.exs` add any configuration that your bot needs.
use Mix.Config

config :alice,
  api_key: System.get_env("SLACK_API_TOKEN"),
  state_backend: :redis,
  redis: System.get_env("REDIS_URL")

config :alice_google_images,
  cse_id: System.get_env("GOOGLE_CSE_ID"),
  cse_token: System.get_env("GOOGLE_CSE_TOKEN"),
  safe_search_level: :medium

With that, you're done! Run your bot with `iex -S mix` or `mix run --no-halt`.

### Deploying to Heroku

Create a new heroku app running Elixir.
heroku create --buildpack ""

Create a file called `heroku_buildpack.config` at the root of your project.


Create a `Procfile` at the root of your project. If you don't create the proc
as a `worker`, Heroku will assume it's a web process and will terminate it for
not binding to port 80.
worker: mix run --no-halt

You may also need to reconfigure Heroku to run the worker.
heroku ps:scale web=0 worker=1

Add your slack token and any other environment variables to Heroku
heroku config:set SLACK_API_TOKEN=xoxb-23486423876-HjgF354JHG7k567K4j56Gk3o

Push to Heroku
git add -A
git commit -m "initial commit"
git push heroku master

Your bot should be good to go. :metal:

## Creating a Route Handler Plugin

### First Steps

mix new alice_google_images
cd alice_google_images
rm lib/alice_google_images.ex test/alice_google_images_test.exs
mkdir -p lib/alice/handlers
mkdir -p test/alice/handlers
touch lib/alice/handlers/google_images.ex test/alice/handlers/google_images_test.exs

### Configuring the App

In `mix.exs`, update `application` and `deps` to look like the following:

def application do
  [applications: []]

defp deps do
    {:alice, "~> 0.4.0"}

### Writing Route Handlers

In `lib/alice/handlers/google_images.ex`:

defmodule Alice.Handlers.GoogleImages do
  use Alice.Router

  command ~r/(image|img)\s+me (?<term>.+)/i, :fetch
  route   ~r/(image|img)\s+me (?<term>.+)/i, :fetch

  @doc "`img me alice in wonderland` - gets a random image from Google Images"
  def fetch(conn) do
    |> Alice.Conn.last_capture
    |> get_images
    |> select_image
    |> reply(conn)


### Registering Handlers

In the `mix.exs` file of your bot, add your handler to the list of handlers to
register on start

def application do
  [ applications: [:alice],
    mod: {Alice, [Alice.Handlers.GoogleImages, ...] } ]