Help language development. Donate to The Perl Foundation

Matrix::Bot cpan:TYIL last updated on 2019-07-16





Patrick Spek [email protected]




A framework for writing Matrix bots


Install this module through zef:

zef install Matrix::Bot


Configuring the bot

First off, you have to instantiate the bot correctly. For this, a few arguments must be passed to new.

use Matrix::Bot;

my $bot =
    home-server => "",
    username => %*ENV<USER>,
    password => "",
    access-token => "",
    plugins => [],


You must specify a password or access-token. If you supply both, the password will be ignored, and the access-token will be used directly. The list of plugins has to be filled with classes which implement Matrix::Bot::Plugin.

The run call starts the bots event loop. It will connect to Matrix, and start retrieving new messages on the channels it is joined in.


The simplest usage of the module would be using the handle-room-text method in a plugin. For instance, to repond to "ping" messages with a "pong", you can write a plugin as follows.

use Matrix::Bot::Plugin;

class Local::Matrix::Plugin is Matrix::Bot::Plugin {
    multi method handle-room-text ($e where * eq "ping") {


There is logging available in the module, through LogP6. This same logging object can be accessed by plugins, so they can log to the same stream when desired. To show all logging, you can set up a filter.

use LogP6 :configure;

filter(name => "", level => $trace, :update);

If you only want certain logging to be shown, you can set up one or more cliche calls instead. For instance, the following cliche shows only the messages on a channel.

    name => "messages",
    matcher => "Matrix::Bot/message",
    grooves => (
            pattern => "%msg",
            handle => $*OUT,
            filter(level => $info),

More information on how to use cliches, filters and LogP6 in general can be found in the LogP6 documentation.

The following traits are used throughout Matrix::Bot:


This module is distributed under the terms of the AGPL-3.0.