Skip to content

Checks

Shows how to restrict a command to a specific set of users using a check. The !secret command is only accessible to users in the allowed_users set — anyone else receives an "Access denied" reply.

from matrix import Bot, Context
from matrix.errors import CheckError

bot = Bot()

allowed_users = {"@alice:matrix.org", "@bob:matrix.org"}


@bot.command(name="secret")
async def secret_command(ctx: Context) -> None:
    await ctx.reply("🎉 Welcome to the secret club!")


@secret_command.check
async def is_allowed_user(ctx: Context) -> bool:
    if ctx.sender in allowed_users:
        return True
    return False


@secret_command.error(CheckError)
async def permission_error_handler(ctx: Context, error: CheckError) -> None:
    await ctx.reply(f"Access denied: {error}")


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

Key points:

  • @secret_command.check decorates an async function that returns True (allow) or False (deny). Returning False raises a CheckError.
  • @secret_command.error(CheckError) handles the denial and sends a friendly reply instead of silently failing.
  • ctx.sender is the full Matrix ID of the user who sent the command (e.g. @alice:matrix.org).

See the Checks guide for built-in checks like @is_owner and how to compose multiple checks.