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

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

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

[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

## 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.2"},
    {: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 `elixir_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.2"}

### 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)


### The Elixir Formatter and Alice

If you want the Elixir formatter to omit the parens on `command/2` and
`route/2`, simply [import] the alice config in your `.formatter.exs`:


# my_handler/.formatter.exs
  # ...

  import_deps: [:alice]

### Testing Handlers

Alice provides several helpers to make it easy to test your handlers.  First
you'll need to invoke to add `use Alice.HandlersCase, handlers: [YourHandler]`
passing it the handler you're trying to test. Then you can use
`message_received()` within your test, which will simulate a message coming in
from the chat backend and route it through to the handlers appropriately.  If
you're wanting to invoke a command, you'll need to make sure your message
includes `<@alice>` within the string. From there you can use either
`first_reply()` to get the first reply sent out or `all_replies()` which will
return a List of replies that have been received during your test. You can use
either to use normal assertions on to ensure your handler behaves in the manner
you expect.

In `test/alice/handlers/google_images_test.exs`:

defmodule Alice.Handlers.GoogleImagesTest do
  use Alice.HandlersCase, handlers: Alice.Handlers.GoogleImages

  test "it fetches an image when asked" do
    send_message("img me example image")

    assert first_reply() == ""

### 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, ...] } ]