Igor

Igor allows you to write bots for Matrix.

Installation

The package can be installed by adding igor to your list of dependencies in mix.exs:

def deps do
  [
    {:igor, "~> 0.1.0"}
  ]
end

Igor depends on html5ever_elixir, which in turn depends on the html5ever Rust library, so to compile Igor, you will need to install Rust. (Also, html5ever_elixir currently does not work with OTP 22, so you must use a lower version of OTP until it is fixed.)

Running the bot

Standalone

To run Igor on its own, create a new Elixir project that depends on it and on any plugins that you want to use, and run mix deps.get to fetch the dependencies. Then create a config/config.exs file (see config/config_sample.exs for an example), and call mix igor.run to start the bot.

As part of an application

Igor can also be started from within another Elixir application by calling

Igor.start_link(opts)

where opts is a keyword list as described in the configuring section below. Or it can be started by a supervisor:

children = [
  {Igor, opts}
]
Supervisor.start_link(children, strategy: :one_for_one)

Configuring

Igor takes the following configuration parameters:

• client: (optional) something that implements Polyjuice.Client.API
• homeserver_url: (required if client: is not set) the base URL of the homeserver
• access_token: (required if client: is not set) the access token for the bot user to authenticate with the homeserver
• device_id: (optional) the device ID for the bot's session (currenty unused)
• bot_name: (optional) the bot's name, for use with responding to commands. Default: igor
• mxid: (required) the bot's Matrix user ID
• aka: (optional) list other names that the bot will respond to for commands. Default: []
• command_prefixes: (optional) list prefixes that can be used for triggering commands. Default: []
• responders: (optional) list of responders to use. Default: []
• storage: (optional, recommended) persistent storage to use. The default value is not suitable for production use, since it does not persist data across restarts. Default: {Igor.Storage, :ets, []}

Responders

Igor uses responders to respond to Matrix events, and comes with some sample responders. For information on writing your own responder, see the documentation for Igor.Responder.