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.2.1"}
  ]
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.

Note that html5ever_elixir 0.7.0 does not work with OTP 22, but html5ever_elixir 0.8.0 does not compile with older versions of Rust (notably, the version of Rust shipped with Debian Buster), so there isn't a single version of html5ever_elixir that will work universally. Currently, mix.lock specifies version 0.7.0, but if you need/want to use version 0.8.0, run mix deps.unlock html5ever rustler and then mix deps.get.

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:

start_client: (optional) a function that starts a client process and returns {:ok, pid, client}, where client is something that implements Polyjuice.Client.API. The function will be given three arguments: a Polyjuice.Client.Handler, a Polyjuice.Client.Storage, and a sync filter.
make_client: (optional) a function that returns something that implements Polyjuice.Client.API. The function will be given three arguments: a Polyjuice.Client.Handler, a Polyjuice.Client.Storage, and a sync filter.
client: (optional) a Polyjuice.Client.API. The start_client option takes precedence over make_client, which takes precedence over client. If none of these options is specified, Igor will create a new Polyjuice.Client using the other options given.
homeserver_url: (required if start_client, make_client, and client are not set) the base URL of the homeserver
access_token: (optional) the access token for the bot user to authenticate with the homeserver
bot_name: (optional) the bot's name, for use with responding to commands. Default: igor
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, []}
accept_invites: (optional) whether or not to accept invites. If true, accept all invites. If false, reject all invites. If a list of strings, accept invites from any of the users IDs listed, and reject invites from others. Default: true

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.