Update Filters#

Filters are objects that can be used to filter the content of incoming updates. Read more about how filters work.

Details#

pyrogram.filters.create(func: Callable, name: str = None, **kwargs) → Filter#

Easily create a custom filter.

Custom filters give you extra control over which updates are allowed or not to be processed by your handlers.

Parameters:

  • func (Callable) – A function that accepts three positional arguments (filter, client, update) and returns a boolean: True if the update should be handled, False otherwise. The filter argument refers to the filter itself and can be used to access keyword arguments (read below). The client argument refers to the Client that received the update. The update argument type will vary depending on which Handler is coming from. For example, in a MessageHandler the update argument will be a Message; in a CallbackQueryHandler the update will be a CallbackQuery. Your function body can then access the incoming update attributes and decide whether to allow it or not.

  • name (str, optional) – Your filter’s name. Can be anything you like. Defaults to “CustomFilter”.

  • **kwargs (any, optional) – Any keyword argument you would like to pass. Useful when creating parameterized custom filters, such as command() or regex().

pyrogram.filters.all = <pyrogram.filters.all_filter object>#

Filter all messages.

pyrogram.filters.me = <pyrogram.filters.me_filter object>#

Filter messages generated by you yourself.

pyrogram.filters.bot = <pyrogram.filters.bot_filter object>#

Filter messages coming from bots.

pyrogram.filters.incoming = <pyrogram.filters.incoming_filter object>#

Filter incoming messages. Messages sent to your own chat (Saved Messages) are also recognised as incoming.

pyrogram.filters.outgoing = <pyrogram.filters.outgoing_filter object>#

Filter outgoing messages. Messages sent to your own chat (Saved Messages) are not recognized as outgoing.

pyrogram.filters.text = <pyrogram.filters.text_filter object>#

Filter text messages.

pyrogram.filters.reply = <pyrogram.filters.reply_filter object>#

Filter messages that are replies to other messages.

pyrogram.filters.forwarded = <pyrogram.filters.forwarded_filter object>#

Filter messages that are forwarded.

pyrogram.filters.caption = <pyrogram.filters.caption_filter object>#

Filter media messages that contain captions.

pyrogram.filters.audio = <pyrogram.filters.audio_filter object>#

Filter messages that contain Audio objects.

pyrogram.filters.document = <pyrogram.filters.document_filter object>#

Filter messages that contain Document objects.

pyrogram.filters.photo = <pyrogram.filters.photo_filter object>#

Filter messages that contain Photo objects.

pyrogram.filters.sticker = <pyrogram.filters.sticker_filter object>#

Filter messages that contain Sticker objects.

pyrogram.filters.animation = <pyrogram.filters.animation_filter object>#

Filter messages that contain Animation objects.

pyrogram.filters.game = <pyrogram.filters.game_filter object>#

Filter messages that contain Game objects.

pyrogram.filters.video = <pyrogram.filters.video_filter object>#

Filter messages that contain Video objects.

pyrogram.filters.media_group = <pyrogram.filters.media_group_filter object>#

Filter messages containing photos or videos being part of an album.

pyrogram.filters.voice = <pyrogram.filters.voice_filter object>#

Filter messages that contain Voice note objects.

pyrogram.filters.video_note = <pyrogram.filters.video_note_filter object>#

Filter messages that contain VideoNote objects.

pyrogram.filters.contact = <pyrogram.filters.contact_filter object>#

Filter messages that contain Contact objects.

pyrogram.filters.location = <pyrogram.filters.location_filter object>#

Filter messages that contain Location objects.

pyrogram.filters.venue = <pyrogram.filters.venue_filter object>#

Filter messages that contain Venue objects.

pyrogram.filters.web_page = <pyrogram.filters.web_page_filter object>#

Filter messages sent with a webpage preview.

pyrogram.filters.poll = <pyrogram.filters.poll_filter object>#

Filter messages that contain Poll objects.

pyrogram.filters.dice = <pyrogram.filters.dice_filter object>#

Filter messages that contain Dice objects.

pyrogram.filters.media_spoiler = <pyrogram.filters.media_spoiler_filter object>#

Filter media messages that contain a spoiler.

pyrogram.filters.private = <pyrogram.filters.private_filter object>#

Filter messages sent in private chats.

pyrogram.filters.group = <pyrogram.filters.group_filter object>#

Filter messages sent in group or supergroup chats.

pyrogram.filters.channel = <pyrogram.filters.channel_filter object>#

Filter messages sent in channels.

pyrogram.filters.new_chat_members = <pyrogram.filters.new_chat_members_filter object>#

Filter service messages for new chat members.

pyrogram.filters.left_chat_member = <pyrogram.filters.left_chat_member_filter object>#

Filter service messages for members that left the chat.

pyrogram.filters.new_chat_title = <pyrogram.filters.new_chat_title_filter object>#

Filter service messages for new chat titles.

pyrogram.filters.new_chat_photo = <pyrogram.filters.new_chat_photo_filter object>#

Filter service messages for new chat photos.

pyrogram.filters.delete_chat_photo = <pyrogram.filters.delete_chat_photo_filter object>#

Filter service messages for deleted photos.

pyrogram.filters.group_chat_created = <pyrogram.filters.group_chat_created_filter object>#

Filter service messages for group chat creations.

pyrogram.filters.supergroup_chat_created = <pyrogram.filters.supergroup_chat_created_filter object>#

Filter service messages for supergroup chat creations.

pyrogram.filters.channel_chat_created = <pyrogram.filters.channel_chat_created_filter object>#

Filter service messages for channel chat creations.

pyrogram.filters.migrate_to_chat_id = <pyrogram.filters.migrate_to_chat_id_filter object>#

Filter service messages that contain migrate_to_chat_id.

pyrogram.filters.migrate_from_chat_id = <pyrogram.filters.migrate_from_chat_id_filter object>#

Filter service messages that contain migrate_from_chat_id.

pyrogram.filters.pinned_message = <pyrogram.filters.pinned_message_filter object>#

Filter service messages for pinned messages.

pyrogram.filters.game_high_score = <pyrogram.filters.game_high_score_filter object>#

Filter service messages for game high scores.

pyrogram.filters.reply_keyboard = <pyrogram.filters.reply_keyboard_filter object>#

Filter messages containing reply keyboard markups

pyrogram.filters.inline_keyboard = <pyrogram.filters.inline_keyboard_filter object>#

Filter messages containing inline keyboard markups

pyrogram.filters.mentioned = <pyrogram.filters.mentioned_filter object>#

Filter messages containing mentions

pyrogram.filters.via_bot = <pyrogram.filters.via_bot_filter object>#

Filter messages sent via inline bots

pyrogram.filters.video_chat_started = <pyrogram.filters.video_chat_started_filter object>#

Filter messages for started video chats

pyrogram.filters.video_chat_ended = <pyrogram.filters.video_chat_ended_filter object>#

Filter messages for ended video chats

pyrogram.filters.video_chat_members_invited = <pyrogram.filters.video_chat_members_invited_filter object>#

Filter messages for voice chat invited members

pyrogram.filters.service = <pyrogram.filters.service_filter object>#

Filter service messages.

A service message contains any of the following fields set: left_chat_member, new_chat_title, new_chat_photo, delete_chat_photo, group_chat_created, supergroup_chat_created, channel_chat_created, migrate_to_chat_id, migrate_from_chat_id, pinned_message, game_score, video_chat_started, video_chat_ended, video_chat_members_invited.

pyrogram.filters.media = <pyrogram.filters.media_filter object>#

Filter media messages.

A media message contains any of the following fields set: audio, document, photo, sticker, video, animation, voice, video_note, contact, location, venue, poll.

pyrogram.filters.scheduled = <pyrogram.filters.scheduled_filter object>#

Filter messages that have been scheduled (not yet sent).

pyrogram.filters.from_scheduled = <pyrogram.filters.from_scheduled_filter object>#

Filter new automatically sent messages that were previously scheduled.

pyrogram.filters.linked_channel = <pyrogram.filters.linked_channel_filter object>#

Filter messages that are automatically forwarded from the linked channel to the group chat.

pyrogram.filters.command(commands: Union[str, List[str]], prefixes: Union[str, List[str]] = '/', case_sensitive: bool = False)#

Filter commands, i.e.: text messages starting with “/” or any other custom prefix.

Parameters:

  • commands (str | list) – The command or list of commands as string the filter should look for. Examples: “start”, [“start”, “help”, “settings”]. When a message text containing a command arrives, the command itself and its arguments will be stored in the command field of the Message.

  • prefixes (str | list, optional) – A prefix or a list of prefixes as string the filter should look for. Defaults to “/” (slash). Examples: “.”, “!”, [“/”, “!”, “.”], list(“.:!”). Pass None or “” (empty string) to allow commands with no prefix at all.

  • case_sensitive (bool, optional) – Pass True if you want your command(s) to be case sensitive. Defaults to False. Examples: when True, command=”Start” would trigger /Start but not /start.

pyrogram.filters.regex(pattern: Union[str, Pattern], flags: int = 0)#

Filter updates that match a given regular expression pattern.

Can be applied to handlers that receive one of the following updates:

When a pattern matches, all the Match Objects are stored in the matches field of the update object itself.

Parameters:

  • pattern (str | Pattern) – The regex pattern as string or as pre-compiled pattern.

  • flags (int, optional) – Regex flags.

class pyrogram.filters.user(users: Union[int, str, List[Union[int, str]]] = None)#

Filter messages coming from one or more users.

You can use set bound methods to manipulate the users container.

Parameters:

users (int | str | list) – Pass one or more user ids/usernames to filter users. For you yourself, “me” or “self” can be used as well. Defaults to None (no users).

class pyrogram.filters.chat(chats: Union[int, str, List[Union[int, str]]] = None)#

Filter messages coming from one or more chats.

You can use set bound methods to manipulate the chats container.

Parameters:

chats (int | str | list) – Pass one or more chat ids/usernames to filter chats. For your personal cloud (Saved Messages) you can simply use “me” or “self”. Defaults to None (no chats).