Filters
Basics
Filter factory greatly simplifies the reuse of filters when registering handlers.
Filters factory
- class aiogram.dispatcher.filters.FiltersFactory(dispatcher)[source]
Bases:
object
Filters factory
- bind(callback: Union[Callable, AbstractFilter], validator: Optional[Callable] = None, event_handlers: Optional[List[Handler]] = None, exclude_event_handlers: Optional[Iterable[Handler]] = None)[source]
Register filter
- Parameters
callback – callable or subclass of
AbstractFilter
validator – custom validator.
event_handlers – list of instances of
Handler
exclude_event_handlers – list of excluded event handlers (
Handler
)
- unbind(callback: Union[Callable, AbstractFilter])[source]
Unregister filter
- Parameters
callback – callable of subclass of
AbstractFilter
- resolve(event_handler, *custom_filters, **full_config) List[Union[Callable, AbstractFilter]] [source]
Resolve filters to filters-set
- Parameters
event_handler –
custom_filters –
full_config –
- Returns
Builtin filters
aiogram
has some builtin filters. Here you can see all of them:
Command
- class aiogram.dispatcher.filters.Command(commands: Union[Iterable[Union[str, BotCommand]], str, BotCommand], prefixes: Union[Iterable, str] = '/', ignore_case: bool = True, ignore_mention: bool = False, ignore_caption: bool = True)[source]
Bases:
Filter
You can handle commands by using this filter.
If filter is successful processed the
Command.CommandObj
will be passed to the handler arguments.By default this filter is registered for messages and edited messages handlers.
Filter can be initialized from filters factory or by simply creating instance of this class.
Examples:
@dp.message_handler(commands=['myCommand']) @dp.message_handler(Command(['myCommand'])) @dp.message_handler(commands=['myCommand'], commands_prefix='!/')
- Parameters
commands – Command or list of commands always without leading slashes (prefix)
prefixes – Allowed commands prefix. By default is slash. If you change the default behavior pass the list of prefixes to this argument.
ignore_case – Ignore case of the command
ignore_mention – Ignore mention in command (By default this filter pass only the commands addressed to current bot)
ignore_caption –
Ignore caption from message (in message types like photo, video, audio, etc) By default is True. If you want check commands in captions, you also should set required content_types.
Examples:
@dp.message_handler(commands=['myCommand'], commands_ignore_caption=False, content_types=ContentType.ANY) @dp.message_handler(Command(['myCommand'], ignore_caption=False), content_types=[ContentType.TEXT, ContentType.DOCUMENT])
- classmethod validate(full_config: Dict[str, Any]) Optional[Dict[str, Any]] [source]
Validator for filters factory
From filters factory this filter can be registered with arguments:
command
commands_prefix
(will be passed asprefixes
)commands_ignore_mention
(will be passed asignore_mention
)commands_ignore_caption
(will be passed asignore_caption
)
- Parameters
full_config –
- Returns
config or empty dict
- async check(message: Message)[source]
Will be called when filters checks.
This method must be overridden.
- Parameters
args –
- Returns
- class CommandObj(prefix: str = '/', command: str = '', mention: Optional[str] = None, args: Optional[str] = None)[source]
Bases:
object
Instance of this object is always has command and it prefix.
Can be passed as keyword argument
command
to the handler- prefix: str = '/'
Command without prefix and mention
- command: str = ''
Mention (if available)
- mention: str = None
Command argument
- property mentioned: bool
This command has mention?
- Returns
- property text: str
Generate original text from object
- Returns
CommandStart
- class aiogram.dispatcher.filters.CommandStart(deep_link: Optional[Union[str, Pattern[str]]] = None, encoded: bool = False)[source]
Bases:
Command
This filter based on
Command
filter but can handle only/start
command.Also this filter can handle deep-linking arguments.
Example:
@dp.message_handler(CommandStart(re.compile(r'ref-([\d]+)')))
- Parameters
deep_link – string or compiled regular expression (by
re.compile(...)
).encoded – set True if you’re waiting for encoded payload (default - False).
CommandHelp
- class aiogram.dispatcher.filters.CommandHelp[source]
Bases:
Command
This filter based on
Command
filter but can handle only/help
command.Filter can be initialized from filters factory or by simply creating instance of this class.
Examples:
@dp.message_handler(commands=['myCommand']) @dp.message_handler(Command(['myCommand'])) @dp.message_handler(commands=['myCommand'], commands_prefix='!/')
- Parameters
commands – Command or list of commands always without leading slashes (prefix)
prefixes – Allowed commands prefix. By default is slash. If you change the default behavior pass the list of prefixes to this argument.
ignore_case – Ignore case of the command
ignore_mention – Ignore mention in command (By default this filter pass only the commands addressed to current bot)
ignore_caption –
Ignore caption from message (in message types like photo, video, audio, etc) By default is True. If you want check commands in captions, you also should set required content_types.
Examples:
@dp.message_handler(commands=['myCommand'], commands_ignore_caption=False, content_types=ContentType.ANY) @dp.message_handler(Command(['myCommand'], ignore_caption=False), content_types=[ContentType.TEXT, ContentType.DOCUMENT])
CommandSettings
- class aiogram.dispatcher.filters.CommandSettings[source]
Bases:
Command
This filter based on
Command
filter but can handle only/settings
command.Filter can be initialized from filters factory or by simply creating instance of this class.
Examples:
@dp.message_handler(commands=['myCommand']) @dp.message_handler(Command(['myCommand'])) @dp.message_handler(commands=['myCommand'], commands_prefix='!/')
- Parameters
commands – Command or list of commands always without leading slashes (prefix)
prefixes – Allowed commands prefix. By default is slash. If you change the default behavior pass the list of prefixes to this argument.
ignore_case – Ignore case of the command
ignore_mention – Ignore mention in command (By default this filter pass only the commands addressed to current bot)
ignore_caption –
Ignore caption from message (in message types like photo, video, audio, etc) By default is True. If you want check commands in captions, you also should set required content_types.
Examples:
@dp.message_handler(commands=['myCommand'], commands_ignore_caption=False, content_types=ContentType.ANY) @dp.message_handler(Command(['myCommand'], ignore_caption=False), content_types=[ContentType.TEXT, ContentType.DOCUMENT])
CommandPrivacy
- class aiogram.dispatcher.filters.CommandPrivacy[source]
Bases:
Command
This filter based on
Command
filter but can handle only/privacy
command.Filter can be initialized from filters factory or by simply creating instance of this class.
Examples:
@dp.message_handler(commands=['myCommand']) @dp.message_handler(Command(['myCommand'])) @dp.message_handler(commands=['myCommand'], commands_prefix='!/')
- Parameters
commands – Command or list of commands always without leading slashes (prefix)
prefixes – Allowed commands prefix. By default is slash. If you change the default behavior pass the list of prefixes to this argument.
ignore_case – Ignore case of the command
ignore_mention – Ignore mention in command (By default this filter pass only the commands addressed to current bot)
ignore_caption –
Ignore caption from message (in message types like photo, video, audio, etc) By default is True. If you want check commands in captions, you also should set required content_types.
Examples:
@dp.message_handler(commands=['myCommand'], commands_ignore_caption=False, content_types=ContentType.ANY) @dp.message_handler(Command(['myCommand'], ignore_caption=False), content_types=[ContentType.TEXT, ContentType.DOCUMENT])
Text
- class aiogram.dispatcher.filters.Text(equals: Optional[Union[str, LazyProxy, Iterable[Union[str, LazyProxy]]]] = None, contains: Optional[Union[str, LazyProxy, Iterable[Union[str, LazyProxy]]]] = None, startswith: Optional[Union[str, LazyProxy, Iterable[Union[str, LazyProxy]]]] = None, endswith: Optional[Union[str, LazyProxy, Iterable[Union[str, LazyProxy]]]] = None, ignore_case=False)[source]
Bases:
Filter
Simple text filter
Check text for one of pattern. Only one mode can be used in one filter. In every pattern, a single string is treated as a list with 1 element.
- Parameters
equals – True if object’s text in the list
contains – True if object’s text contains all strings from the list
startswith – True if object’s text starts with any of strings from the list
endswith – True if object’s text ends with any of strings from the list
ignore_case – case insensitive
- classmethod validate(full_config: Dict[str, Any])[source]
Here method
validate
is optional. If you need to use filter from filters factory you need to override this method.- Parameters
full_config – dict with arguments passed to handler registrar
- Returns
Current filter config
- async check(obj: Union[Message, CallbackQuery, InlineQuery, Poll])[source]
Will be called when filters checks.
This method must be overridden.
- Parameters
args –
- Returns
HashTag
- class aiogram.dispatcher.filters.HashTag(hashtags=None, cashtags=None)[source]
Bases:
Filter
Filter for hashtag’s and cashtag’s
Regexp
- class aiogram.dispatcher.filters.Regexp(regexp)[source]
Bases:
Filter
Regexp filter for messages and callback query
- classmethod validate(full_config: Dict[str, Any])[source]
Here method
validate
is optional. If you need to use filter from filters factory you need to override this method.- Parameters
full_config – dict with arguments passed to handler registrar
- Returns
Current filter config
- async check(obj: Union[Message, CallbackQuery, InlineQuery, Poll])[source]
Will be called when filters checks.
This method must be overridden.
- Parameters
args –
- Returns
RegexpCommandsFilter
- class aiogram.dispatcher.filters.RegexpCommandsFilter(regexp_commands)[source]
Bases:
BoundFilter
Check commands by regexp in message
- key = 'regexp_commands'
Unique name of the filter argument. You need to override this attribute.
ContentTypeFilter
- class aiogram.dispatcher.filters.ContentTypeFilter(content_types)[source]
Bases:
BoundFilter
Check message content type
- key = 'content_types'
Unique name of the filter argument. You need to override this attribute.
- required = True
If
True
this filter will be added to the all of the registered handlers
- default = ['text']
Default value for configure required filters
IsSenderContact
- class aiogram.dispatcher.filters.IsSenderContact(is_sender_contact: bool)[source]
Bases:
BoundFilter
Filter check that the contact matches the sender
is_sender_contact=True - contact matches the sender is_sender_contact=False - result will be inverted
- key = 'is_sender_contact'
Unique name of the filter argument. You need to override this attribute.
StateFilter
- class aiogram.dispatcher.filters.StateFilter(dispatcher, state)[source]
Bases:
BoundFilter
Check user state
- key = 'state'
Unique name of the filter argument. You need to override this attribute.
- required = True
If
True
this filter will be added to the all of the registered handlers
ExceptionsFilter
- class aiogram.dispatcher.filters.ExceptionsFilter(exception)[source]
Bases:
BoundFilter
Filter for exceptions
- key = 'exception'
Unique name of the filter argument. You need to override this attribute.
IDFilter
- class aiogram.dispatcher.filters.builtin.IDFilter(user_id: Optional[Union[Iterable[Union[int, str]], str, int]] = None, chat_id: Optional[Union[Iterable[Union[int, str]], str, int]] = None)[source]
Bases:
Filter
- Parameters
user_id –
chat_id –
- classmethod validate(full_config: Dict[str, Any]) Optional[Dict[str, Any]] [source]
Here method
validate
is optional. If you need to use filter from filters factory you need to override this method.- Parameters
full_config – dict with arguments passed to handler registrar
- Returns
Current filter config
- async check(obj: Union[Message, CallbackQuery, InlineQuery, ChatMemberUpdated, ChatJoinRequest])[source]
Will be called when filters checks.
This method must be overridden.
- Parameters
args –
- Returns
AdminFilter
- class aiogram.dispatcher.filters.AdminFilter(is_chat_admin: Optional[Union[Iterable[Union[int, str]], str, int, bool]] = None)[source]
Bases:
Filter
Checks if user is admin in a chat. If is_chat_admin is not set, the filter will check in the current chat (correct only for messages). is_chat_admin is required for InlineQuery.
- classmethod validate(full_config: Dict[str, Any]) Optional[Dict[str, Any]] [source]
Here method
validate
is optional. If you need to use filter from filters factory you need to override this method.- Parameters
full_config – dict with arguments passed to handler registrar
- Returns
Current filter config
- async check(obj: Union[Message, CallbackQuery, InlineQuery, ChatMemberUpdated]) bool [source]
Will be called when filters checks.
This method must be overridden.
- Parameters
args –
- Returns
IsReplyFilter
- class aiogram.dispatcher.filters.IsReplyFilter(is_reply)[source]
Bases:
BoundFilter
Check if message is replied and send reply message to handler
- key = 'is_reply'
Unique name of the filter argument. You need to override this attribute.
ForwardedMessageFilter
- class aiogram.dispatcher.filters.ForwardedMessageFilter(is_forwarded: bool)[source]
Bases:
BoundFilter
- key = 'is_forwarded'
Unique name of the filter argument. You need to override this attribute.
ChatTypeFilter
- class aiogram.dispatcher.filters.ChatTypeFilter(chat_type: Container[ChatType])[source]
Bases:
BoundFilter
- key = 'chat_type'
Unique name of the filter argument. You need to override this attribute.
- async check(obj: Union[Message, CallbackQuery, ChatMemberUpdated, InlineQuery])[source]
Will be called when filters checks.
This method must be overridden.
- Parameters
args –
- Returns
MediaGroupFilter
- class aiogram.dispatcher.filters.MediaGroupFilter(is_media_group: bool)[source]
Bases:
BoundFilter
Check if message is part of a media group.
is_media_group=True - the message is part of a media group is_media_group=False - the message is NOT part of a media group
- key = 'is_media_group'
Unique name of the filter argument. You need to override this attribute.
Making own filters (Custom filters)
Own filter can be:
any callable object
any async function
any anonymous function (Example:
lambda msg: msg.text == 'spam'
)Subclass of
AbstractFilter
,Filter
orBoundFilter
AbstractFilter
- class aiogram.dispatcher.filters.AbstractFilter[source]
Bases:
ABC
Abstract class for custom filters.
- abstract classmethod validate(full_config: Dict[str, Any]) Optional[Dict[str, Any]] [source]
Validate and parse config.
This method will be called by the filters factory when you bind this filter. Must be overridden.
- Parameters
full_config – dict with arguments passed to handler registrar
- Returns
Current filter config
Filter
- class aiogram.dispatcher.filters.Filter[source]
Bases:
AbstractFilter
You can make subclasses of that class for custom filters.
Method
check
must be overridden- classmethod validate(full_config: Dict[str, Any]) Optional[Dict[str, Any]] [source]
Here method
validate
is optional. If you need to use filter from filters factory you need to override this method.- Parameters
full_config – dict with arguments passed to handler registrar
- Returns
Current filter config
BoundFilter
- class aiogram.dispatcher.filters.BoundFilter[source]
Bases:
Filter
To easily create your own filters with one parameter, you can inherit from this filter.
You need to implement
__init__
method with single argument related with key attribute andcheck
method where you need to implement filter logic.- key = None
Unique name of the filter argument. You need to override this attribute.
- required = False
If
True
this filter will be added to the all of the registered handlers
- default = None
Default value for configure required filters
class ChatIdFilter(BoundFilter):
key = 'chat_id'
def __init__(self, chat_id: typing.Union[typing.Iterable, int]):
if isinstance(chat_id, int):
chat_id = [chat_id]
self.chat_id = chat_id
def check(self, message: types.Message) -> bool:
return message.chat.id in self.chat_id
dp.filters_factory.bind(ChatIdFilter, event_handlers=[dp.message_handlers])