Flags is a markers for handlers that can be used in middlewares or special utilities to make classification of the handlers.

Flags can be added to the handler via decorators, handlers registration or filters.

Via decorators#

For example mark handler with chat_action flag

from aiogram import flags

async def my_handler(message: Message)

Or just for rate-limit or something else

from aiogram import flags

@flags.rate_limit(rate=2, key="something")
async def my_handler(message: Message)

Via handler registration method#

@router.message(..., flags={'chat_action': 'typing', 'rate_limit': {'rate': 5}})

Via filters#

class Command(Filter):

    def update_handler_flags(self, flags: Dict[str, Any]) -> None:
        commands = flags.setdefault("commands", [])

Use in middlewares#

aiogram.dispatcher.flags.check_flags(handler: HandlerObject | Dict[str, Any], magic: MagicFilter) Any[source]#

Check flags via magic filter

  • handler – handler object or data

  • magic – instance of the magic


the result of magic filter check

aiogram.dispatcher.flags.extract_flags(handler: HandlerObject | Dict[str, Any]) Dict[str, Any][source]#

Extract flags from handler or middleware context data


handler – handler object or data


dictionary with all handler flags

aiogram.dispatcher.flags.get_flag(handler: HandlerObject | Dict[str, Any], name: str, *, default: Any | None = None) Any[source]#

Get flag by name

  • handler – handler object or data

  • name – name of the flag

  • default – default value (None)


value of the flag or default

Example in middlewares#

async def my_middleware(handler, event, data):
    typing = get_flag(data, "typing")  # Check that handler marked with `typing` flag
    if not typing:
        return await handler(event, data)

    async with ChatActionSender.typing(chat_id=event.chat.id):
        return await handler(event, data)

Use in utilities#

For example you can collect all registered commands with handler description and then it can be used for generating commands help

def collect_commands(router: Router) -> Generator[Tuple[Command, str], None, None]:
    for handler in router.message.handlers:
        if "commands" not in handler.flags:  # ignore all handler without commands
        # the Command filter adds the flag with list of commands attached to the handler
        for command in handler.flags["commands"]:
            yield command, handler.callback.__doc__ or ""
    # Recursively extract commands from nested routers
    for sub_router in router.sub_routers:
        yield from collect_commands(sub_router)