Fawkes

Fawkes is a system for building chatbots.

Starting a bot

Fawkes provides an interface that you can use to start a new bot in your applications supervision tree.

Fawkes.start_link([
  name: MyRobot,
  bot_name: "fawkes",
  bot_alias: ".",
  brain: {Fawkes.Brain.Redis, []},
  adapter: {Fawkes.Adapter.Slack, [token: "SOME SLACK TOKEN"]},
  handlers: [
    {Echo, nil},
    {Shipit, urls},
  ]
])

Event Handlers

In order for your bot to do useful things you need to define an event hander:

defmodule EchoHandler do
  @behaviour Fawkes.EventHandler

  alias Fawkes.Bot
  alias Fawkes.Event.Message

  def init(_opts) do
    {:ok, nil}
  end

  def handle_event(%Message{text: "echo " <> text}=event, state) do
    Bot.say(event, text)
    state
  end
  def handle_event(_, state), do: state
end

Your handler can match on any of the events emitted by Fawkes. See the Event module docs for more details.

Listeners

The EventHandler behaviour is the most flexible approach for responding to events. But its not always the most convenient or use friendly approach. Fawkes also provides the Fawkes.Listener module which makes it easy to build custom responders.

defmodule Fawkes.Handlers.Echo do
  @moduledoc false
  use Fawkes.Listener

  @help """
  fawkes echome <text> - Echos the text back to you
  """
  respond ~r/echome (.*)/, fn [match], event ->
    reply(event, match)
  end

  @help """
  echo <text> - Echos the text back to the channel
  """
  hear ~r/^echo (.*)/, fn [match], event ->
    say(event, match)
  end

  @help """
  echocode <text> - Echos the text back to the channel as code
  """
  hear ~r/^echocode (.*)/, fn [match], event ->
    code(event, match)
  end
end

Any handlers defined using the Fawkes.Listener api can be added to the handler list in the same way as other handlers.

Help command

Fawkes provides a built in "help" handler. This handler gets the list handlers and uses the help/0 function defined in each module to create a help message. Because of this, users are encouraged to write help functions for their handlers. Each help message should be written on a single line. If you need to indicate that a listener needs to mention the bot you can write a help message like

@help """
fawkes echo <text> - Echo's the text back to you.
"""
respond(~r/echo (.*)/, fn matches, event ->
end)

You should always use "fawkes" in your help messages. The help handler will automatically replace this with your bots name or alias.

Brains

Fawkes provides an interface that handlers can use to persist values. The default brain is an in memory store. If your bot requires persistence you can use the built in redis brain or implement your own.

Architecture and Adapters

The Adapter's job is to process incoming messages and deliver them to Fawkes' internal EventProducer. Internally, Fawkes uses GenStage to broadcast events to all of the event handlers. Messages from the bot can be sent back to the adapter using the functions in Fawkes.Event. These are delivered to the adapter process which formats and sends the message based on the conventions of that adapter.

Installation

def deps do
  [
    {:fawkes, "~> 0.4"}
  ]
end

enilsen16 / fawkes