Skip to main content

A basic bot for Matrix

Project description


A Python module meant to act as a base class for a Matrix bot.


Python 3.6+


pip install python-matrixbot


The MatrixBot class will connect to the Matrix server, start a listener on each joined room, and listen for room invites from other users. It also includes helper methods you can use to extend the functionality. It is built on the Matrix Python SDK which can be directly accessed via MatrixBot.client

from matrixbot import MatrixBot

# create a new bot
bot = MatrixBot(
    display_name="Example Bot",
# run forever

Get a list of joined rooms:

room_ids = bot.rooms.keys()
room_objects = bot.rooms.values()

Leave abandoned 1-on-1 rooms

for room in bot.rooms.values():

Cache results from external API calls

To prevent abuse of commands that rely on external API calls, MatrixBot includes a very basic caching mechanism. Wrap all API calls in MatrixBot.fetch() to return cached results and automatically refresh stale data.

def get_url(url):
  return response.get(url)

result = bot.fetch(
    "cache_key", lambda: get_url(""), timeout=900

By default the module uses an in-memory cache which is lost between restarts. To create a persistent cache provide the constructor with the path to a sqlite database:

bot = MatrixBot(


Create a subclass to extend and override default features

class MyBot(MatrixBot):
    # override `process_message()` to filter/parse/react to room events:
    def process_message(self, room, event):
        # say hello when a user joins the room
        if event["type"] == "":
            if event["content"]["membership"] == "join":
                self.say(room, "Hello!", mention=event["sender"])

    # override `accept_invite()` to disable auto-join:
    def accept_invite(self, room_id):

bot = MyBot(...)




Brian Ó

Contributions welcome.

About Gibberfish

Gibberfish, Inc is a volunteer nonprofit that develops free tools to promote online privacy for activists and regular people alike. If you like this module and decide to use it in your project, please consider donating $1 to help keep us going. Thanks!

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python-matrixbot-0.0.7.tar.gz (8.7 kB view hashes)

Uploaded source

Built Distribution

python_matrixbot-0.0.7-py3-none-any.whl (11.2 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page