Scheduler

Shows how to run tasks on a cron schedule using @bot.schedule. Tasks run independently of commands — they fire at the specified time whether or not anyone sends a message.

from matrix import Bot, Context

bot = Bot()

room_id = "!your_room_id:matrix.org"  # Replace with your room ID

room = bot.get_room(room_id)


@bot.command("ping")
async def ping(ctx: Context) -> None:
    await ctx.reply("Pong!")


@bot.schedule("* * * * *")
async def scheduled_task() -> None:
    # This task runs every minute.
    await room.send("Scheduled ping!")


@bot.schedule("0 * * * *")
async def hourly_task() -> None:
    # This task runs every hour.
    await room.send("This is your hourly update!")


@bot.schedule("0 9 * * 1-5")
async def weekday_morning_task() -> None:
    # This task runs every weekday at 9 AM.
    await room.send("Good morning! Here's your weekday update!")


bot.start(config="config.yaml")

@bot.schedule accepts a standard 5-field cron expression:

Expression	Meaning
* * * * *	Every minute
0 * * * *	Every hour (on the hour)
0 9 * * 1-5	9 AM every weekday

The scheduled function receives no arguments. To send a message you need a Room object — get one with bot.get_room(room_id) before the bot starts, then call room.send() inside the task.

See the Scheduler reference for the full API.