Filtering events#

Filters is needed for routing updates to the specific handler. Searching of handler is always stops on first match set of filters are pass. By default, all handlers has empty set of filters, so all updates will be passed to first handler that has empty set of filters.

aiogram has some builtin useful filters or you can write own filters.

Builtin filters#

Here is list of builtin filters:

Writing own filters#

Filters can be:

  • Asynchronous function (async def my_filter(*args, **kwargs): pass)

  • Synchronous function (def my_filter(*args, **kwargs): pass)

  • Anonymous function (lambda event: True)

  • Any awaitable object

  • Subclass of aiogram.filters.base.Filter

  • Instances of MagicFilter

and should return bool or dict. If the dictionary is passed as result of filter - resulted data will be propagated to the next filters and handler as keywords arguments.

Base class for own filters#

class aiogram.filters.base.Filter[source]#

If you want to register own filters like builtin filters you will need to write subclass of this class with overriding the __call__ method and adding filter attributes.

abstract async __call__(*args: Any, **kwargs: Any) bool | Dict[str, Any][source]#

This method should be overridden.

Accepts incoming event and should return boolean or dict.


bool or Dict[str, Any]

update_handler_flags(flags: Dict[str, Any]) None[source]#

Also if you want to extend handler flags with using this filter you should implement this method


flags – existing flags, can be updated directly

Own filter example#

For example if you need to make simple text filter:

from aiogram import Router
from aiogram.filters import Filter
from aiogram.types import Message

router = Router()

class MyFilter(Filter):
    def __init__(self, my_text: str) -> None:
        self.my_text = my_text

    async def __call__(self, message: Message) -> bool:
        return message.text == self.my_text

async def my_handler(message: Message):

Combining Filters#

In general, all filters can be combined in two ways

Another possible way#

An alternative way is to combine using special functions (and_f(), or_f(), invert_f() from aiogram.filters module):

and_f(F.text.startswith("show"), F.text.endswith("example"))
or_f(F.text(text="hi"), CommandStart())
and_f(<A>, or_f(<B>, <C>))