Quickstart

Install the simplematrixbotlib package

Installation from pip:

python3 -m pip install simplematrixbotlib

Download git repository:

git clone https://codeberg.org/imbev/simplematrixbotlib.git

Go to Element Web
If you are already using element web, then you may want to use a private session in your browser.
Change the homeserver if you prefer, and enter a new username, password, and/or email into the respective fields.
Save the homeserver, username, and password at a safe location, then complete the captcha.

Your bot's login credentials should resemble the following:

homeserver: https://example.com

username: example_bot

password: secretpassword

Create the bot

(The example source code will be provided in full at the bottom)

Begin by importing the package.

import simplematrixbotlib as botlib

Create a Creds object with your login credentials.

creds = botlib.Creds("https://home.server", "user", "pass")

Create a bot object. This will be used as a handle throughout your project.

bot = botlib.Bot(creds)

If you want to use a prefix in the commands that your bot responds to, it may be useful to assign it to a variable.

PREFIX = '!'

Before creating a function handler for a command, it is necessary to add a listener.

@bot.listener.on_message_event

Create a command by defining a function. The function must be an "async" function with two arguments. Recommended argument names are (room, message) or (room, event)

async def echo(room, message): 
    """
    Example command that "echoes" arguements.
    Usage:
    example_user- !echo say something
    echo_bot- say something
    """

Creating a MessageMatch object is optional, but useful for handling messages. The prefix argument is optional, but is needed when matching prefixes.

    match = botlib.MessageMatch(room, message, bot, PREFIX)

This specific usage of the MessageMatch class will only allow the bot to react to messages that are not from the bot and also start with "!echo".

    if match.is_not_from_this_bot() and match.prefix() and match.command("echo"):

This part of the handler is responsible for sending the response message. The rest of the message following "!echo" will be sent to the same room as the message.

        await bot.api.send_text_message(room.room_id, " ".join(arg for arg in match.args()))

Finally run the bot.

bot.run()

This bot is an echo bot, which "echoes" the arguments of any message that starts with "!echo"(). As many handlers as needed can be added, each with its own handler function and a listener.

Full code of echo bot example

import simplematrixbotlib as botlib

creds = botlib.Creds("https://home.server", "user", "pass")
bot = botlib.Bot(creds)
PREFIX = '!'

@bot.listener.on_message_event
async def echo(room, message):
    match = botlib.MessageMatch(room, message, bot, PREFIX) 

    if match.is_not_from_this_bot() and match.prefix() and match.command("echo"):

        await bot.api.send_text_message(
            room.room_id, " ".join(arg for arg in match.args())
            ) 

bot.run()

Other examples can be found here.

Quickstart

Install the simplematrixbotlib package

Obtain Matrix login credentials

Create the bot