#bot #fractal #api #matrix


API for writing a bot for the Matrix messaging protocol

8 releases (4 breaking)

0.5.2 Feb 21, 2020
0.5.1 Feb 19, 2020
0.4.0 Mar 25, 2019
0.3.1 Jun 21, 2018
0.1.0 Jun 12, 2018

#4 in #fractal

Download history 6/week @ 2020-10-04 4/week @ 2020-10-11 12/week @ 2020-10-18 4/week @ 2020-10-25 6/week @ 2020-11-01 6/week @ 2020-11-08 5/week @ 2020-11-15 13/week @ 2020-11-22 10/week @ 2020-11-29 12/week @ 2020-12-06 4/week @ 2020-12-13 2/week @ 2020-12-20 3/week @ 2020-12-27 14/week @ 2021-01-03 5/week @ 2021-01-10 14/week @ 2021-01-17

93 downloads per month

MIT and GPL-3.0 licenses

252 lines


API for writing Matrix-bots (see matrix.org) in rust.


It uses the Matrix-API provided by the fractal messenger (fractal-matrix-api).

How to use

See the examples-directory



Easy to use API for implementing your own Matrix-Bot (see matrix.org)

Basic setup:

There are two main parts: A MessageHandler and the MatrixBot. The MessageHandler defines what happens with received messages. The MatrixBot consumes your MessageHandler and deals with all the matrix-protocol-stuff, calling your MessageHandler for each new text-message with an ActiveBot handle that allows the handler to respond to the message.

You can write your own MessageHandler by implementing the MessageHandler-trait, or use one provided by this crate (currently only StatelessHandler).

Multple Handlers:

One can register multiple MessageHandlers with a bot. Thus one can "plug and play" different features to ones MatrixBot. Messages are given to each handler in the order of their registration. A message is given to the next handler until one handler returns StopHandling. Thus a message can be handled by multiple handlers as well (for example for "help").


extern crate matrix_bot_api;
use matrix_bot_api::{MatrixBot, MessageType};
use matrix_bot_api::handlers::{StatelessHandler, HandleResult};

fn main() {
    let mut handler = StatelessHandler::new();
    handler.register_handle("shutdown", |bot, _, _| {
        HandleResult::ContinueHandling /* Other handlers might need to clean up after themselves on shutdown */

    handler.register_handle("echo", |bot, message, tail| {
        bot.send_message(&format!("Echo: {}", tail), &message.room, MessageType::TextMessage);

    let mut bot = MatrixBot::new(handler);
    bot.run("your_bot", "secret_password", "https://your.homeserver");

Have a look in the examples/ directory for detailed examples.


~521K SLoC