Listener Class

The Listener class is a class that is used to specify reactions to the events that occur in Matrix rooms. The source is located at simplematrixbotlib/listener.py

Accessing a Listener instance

An instance of the Listener class is automatically created when an instance of the Bot class is created. An example is shown in the following python code.

bot = botlib.Bot(creds)
bot.listener #Instance of the Listener class

Using the on_message_event decorator

The on_message_event method of the Listener class may be used to execute actions based on messages that are sent in rooms that the bot is a member of. Example usage of on_message_event is shown in the following python code.

@bot.listener.on_message_event
async def example(room, message):
    print(f"A message({message.content}) was sent in a room({room.room_id}).")

When any message is sent, the function will be called with room as a Room object representing each room that that the bot is a member of, and message as a RoomMessage object representing the message that was sent.

Using the on_reaction_event decorator

The on_reaction_event decorator method of the Listener class may be used to execute actions based on reactions that are sent in rooms that the bot is a member of. Example usage of on_reaction_event is shown in the following python code.

@bot.listener.on_reaction_event
async def example(room, event, reaction):
    print(f"User {event.source['sender']} reacted with {reaction} to message {event.source['content']['m.relates_to']['event_id']}")

As of the time of writing, m.reaction events are not supported via matrix-nio. To work around this, it is recommended to use the event's source via event.source as a dictionary. An example m.reaction event source is provided for convenience below:

{
    "events": [
        {
            "content": {
                "m.relates_to": {
                    "event_id": "$FNP1EnwKRuzH38LjuYptDSkJpzomVt3tijlBy6yfc10",
                    "key": "😆",
                    "rel_type": "m.annotation"
                }
            },
            "origin_server_ts": 1641348447462,
            "sender": "@krazykirby99999:matrix.org",
            "type": "m.reaction",
            "unsigned": {
                "age": 341
            },
            "event_id": "$rGchfmQQmt2NxnlJ88HzWdVTIW-cfo-DGZFUYbqihBI"
        }
    ]
}

Using the on_custom_event decorator

The on_custom_event method of the Listener class may be used to execute actions based on any event that is sent in rooms that the bot is a member of. Example usage of on_custom_event is shown in the following python code.

import nio

@bot.listener.on_custom_event(nio.InviteMemberEvent)
async def example(room, event):
    if event.membership == "join":
        print(f"A user joined the room({room.room_id}).")
    if event.membership == "leave":
        print(f"A user left the room({room.room_id}).")

The on_custom_event method is almost identical to the on_message_event method. on_custom_event takes an argument that allows the developer to specify the event type for the Bot to respond to. Information on events can be found in the matrix-nio docs.

Using the on_startup decorator

The on_startup method of the Listener class may be used to execute actions upon the starting of the Bot. Example usage of the on_startup method is show in the following python code.

@bot.listener.on_startup
async def room_joined(room_id):
    print(f"This account is a member of a room with the id {room_id}")

When the bot is run, for each room that the Bot is a member of, the function will be called with room_id as a string that corresponds to the room_id of the room.