telegram.ext.filters Module

This module contains the Filters for use with the MessageHandler class.

class telegram.ext.filters.BaseFilter

Bases: abc.ABC

Base class for all Filters.

Filters subclassing from this class can combined using bitwise operators:

And:

>>> (Filters.text & Filters.entity(MENTION))

Or:

>>> (Filters.audio | Filters.video)

Exclusive Or:

>>> (Filters.regex('To Be') ^ Filters.regex('Not 2B'))

Not:

>>> ~ Filters.command

Also works with more than two filters:

>>> (Filters.text & (Filters.entity(URL) | Filters.entity(TEXT_LINK)))
>>> Filters.text & (~ Filters.forwarded)

Note

Filters use the same short circuiting logic as python’s and, or and not. This means that for example:

>>> Filters.regex(r'(a?x)') | Filters.regex(r'(b?x)')

With message.text == x, will only ever return the matches for the first filter, since the second one is never evaluated.

If you want to create your own filters create a class inheriting from either MessageFilter or UpdateFilter and implement a filter() method that returns a boolean: True if the message should be handled, False otherwise. Note that the filters work only as class instances, not actual class objects (so remember to initialize your filter classes).

By default the filters name (what will get printed when converted to a string for display) will be the class name. If you want to overwrite this assign a better name to the name class variable.

name

Name for this filter. Defaults to the type of filter.

Type

str

data_filter

Whether this filter is a data filter. A data filter should return a dict with lists. The dict will be merged with telegram.ext.CallbackContext’s internal dict in most cases (depends on the handler).

Type

bool

class telegram.ext.filters.Filters

Bases: object

Predefined filters for use as the filter argument of telegram.ext.MessageHandler.

Examples

Use MessageHandler(Filters.video, callback_method) to filter all video messages. Use MessageHandler(Filters.contact, callback_method) for all contacts. etc.

all = Filters.all

All Messages.

animation = Filters.animation

Messages that contain telegram.Animation.

audio = Filters.audio

Messages that contain telegram.Audio.

caption = Filters.caption

Messages with a caption. If a list of strings is passed, it filters messages to only allow those whose caption is appearing in the given list.

Examples

MessageHandler(Filters.caption, callback_method)

Parameters

update (List[str] | Tuple[str], optional) – Which captions to allow. Only exact matches are allowed. If not specified, will allow any message with a caption.

class caption_entity(entity_type)

Bases: telegram.ext.filters.MessageFilter

Filters media messages to only allow those which have a telegram.MessageEntity where their type matches entity_type.

Examples

Example MessageHandler(Filters.caption_entity("hashtag"), callback_method)

Parameters

entity_type – Caption Entity type to check for. All types can be found as constants in telegram.MessageEntity.

class caption_regex(pattern)

Bases: telegram.ext.filters.MessageFilter

Filters updates by searching for an occurrence of pattern in the message caption.

This filter works similarly to Filters.regex, with the only exception being that it applies to the message caption instead of the text.

Examples

Use MessageHandler(Filters.photo & Filters.caption_regex(r'help'), callback) to capture all photos with caption containing the word ‘help’.

Note

This filter will not work on simple text messages, but only on media with caption.

Parameters

pattern (str | Pattern) – The regex pattern.

class chat(chat_id=None, username=None, allow_empty=False)

Bases: telegram.ext.filters.Filters._ChatUserBaseFilter

Filters messages to allow only those which are from a specified chat ID or username.

Examples

MessageHandler(Filters.chat(-1234), callback_method)

Warning

chat_ids will give a copy of the saved chat ids as frozenset. This is to ensure thread safety. To add/remove a chat, you should use add_usernames(), add_chat_ids(), remove_usernames() and remove_chat_ids(). Only update the entire set by filter.chat_ids/usernames = new_set, if you are entirely sure that it is not causing race conditions, as this will complete replace the current set of allowed chats.

Parameters
  • chat_id (telegram.utils.types.SLT[int], optional) – Which chat ID(s) to allow through.

  • username (telegram.utils.types.SLT[str], optional) – Which username(s) to allow through. Leading '@' s in usernames will be discarded.

  • allow_empty (bool, optional) – Whether updates should be processed, if no chat is specified in chat_ids and usernames. Defaults to False

Raises

RuntimeError – If chat_id and username are both present.

chat_ids

Which chat ID(s) to allow through.

Type

set(int), optional

usernames

Which username(s) (without leading '@') to allow through.

Type

set(str), optional

allow_empty

Whether updates should be processed, if no chat is specified in chat_ids and usernames.

Type

bool, optional

add_chat_ids(chat_id)

Add one or more chats to the allowed chat ids.

Parameters

chat_id (telegram.utils.types.SLT[int], optional) – Which chat ID(s) to allow through.

add_usernames(username)

Add one or more chats to the allowed usernames.

Parameters

username (telegram.utils.types.SLT[str], optional) – Which username(s) to allow through. Leading '@' s in usernames will be discarded.

get_chat_or_user(message)
remove_chat_ids(chat_id)

Remove one or more chats from allowed chat ids.

Parameters

chat_id (telegram.utils.types.SLT[int], optional) – Which chat ID(s) to disallow through.

remove_usernames(username)

Remove one or more chats from allowed usernames.

Parameters

username (telegram.utils.types.SLT[str], optional) – Which username(s) to disallow through. Leading '@' s in usernames will be discarded.

chat_type = Filters.chat_type

Subset for filtering the type of chat.

Examples

Use these filters like: Filters.chat_type.channel or Filters.chat_type.supergroup etc. Or use just Filters.chat_type for all chat types.

channel

Updates from channel

group

Updates from group

supergroup

Updates from supergroup

groups

Updates from group or supergroup

private

Updates sent in private chat

command = Filters.command

Messages with a telegram.MessageEntity.BOT_COMMAND. By default only allows messages starting with a bot command. Pass False to also allow messages that contain a bot command anywhere in the text.

Examples:

MessageHandler(Filters.command, command_at_start_callback)
MessageHandler(Filters.command(False), command_anywhere_callback)

Note

Filters.text also accepts messages containing a command.

Parameters

update (bool, optional) – Whether to only allow messages that start with a bot command. Defaults to True.

contact = Filters.contact

Messages that contain telegram.Contact.

dice = Filters.dice

Dice Messages. If an integer or a list of integers is passed, it filters messages to only allow those whose dice value is appearing in the given list.

Examples

To allow any dice message, simply use MessageHandler(Filters.dice, callback_method). To allow only dice with value 6, use MessageHandler(Filters.dice(6), callback_method). To allow only dice with value 5 or 6, use MessageHandler(Filters.dice([5, 6]), callback_method).

Note

Dice messages don’t have text. If you want to filter either text or dice messages, use Filters.text | Filters.dice.

Parameters

update (telegram.utils.types.SLT[int], optional) – Which values to allow. If not specified, will allow any dice message.

dice

Dice messages with the emoji 🎲. Passing a list of integers is supported just as for Filters.dice.

darts

Dice messages with the emoji 🎯. Passing a list of integers is supported just as for Filters.dice.

basketball

Dice messages with the emoji 🏀. Passing a list of integers is supported just as for Filters.dice.

football

Dice messages with the emoji ⚽. Passing a list of integers is supported just as for Filters.dice.

slot_machine

Dice messages with the emoji 🎰. Passing a list of integers is supported just as for Filters.dice.

bowling

Dice messages with the emoji 🎳. Passing a list of integers is supported just as for Filters.dice.

New in version 13.4.

document = Filters.document

Subset for messages containing a document/file.

Examples

Use these filters like: Filters.document.mp3, Filters.document.mime_type("text/plain") etc. Or use just Filters.document for all document messages.

category

Filters documents by their category in the mime-type attribute

Note

This Filter only filters by the mime_type of the document, it doesn’t check the validity of the document. The user can manipulate the mime-type of a message and send media with wrong types that don’t fit to this handler.

Example

Filters.document.category('audio/') filters all types of audio sent as file, for example ‘audio/mpeg’ or ‘audio/x-wav’.

application

Same as Filters.document.category("application").

audio

Same as Filters.document.category("audio").

image

Same as Filters.document.category("image").

video

Same as Filters.document.category("video").

text

Same as Filters.document.category("text").

mime_type

Filters documents by their mime-type attribute

Note

This Filter only filters by the mime_type of the document, it doesn’t check the validity of document.

The user can manipulate the mime-type of a message and send media with wrong types that don’t fit to this handler.

Example

Filters.document.mime_type('audio/mpeg') filters all audio in mp3 format.

apk

Same as Filters.document.mime_type("application/vnd.android.package-archive").

doc

Same as Filters.document.mime_type("application/msword").

docx

Same as Filters.document.mime_type("application/vnd.openxmlformats-officedocument.wordprocessingml.document").

exe

Same as Filters.document.mime_type("application/x-ms-dos-executable").

gif

Same as Filters.document.mime_type("video/mp4").

jpg

Same as Filters.document.mime_type("image/jpeg").

mp3

Same as Filters.document.mime_type("audio/mpeg").

pdf

Same as Filters.document.mime_type("application/pdf").

py

Same as Filters.document.mime_type("text/x-python").

svg

Same as Filters.document.mime_type("image/svg+xml").

txt

Same as Filters.document.mime_type("text/plain").

targz

Same as Filters.document.mime_type("application/x-compressed-tar").

wav

Same as Filters.document.mime_type("audio/x-wav").

xml

Same as Filters.document.mime_type("application/xml").

zip

Same as Filters.document.mime_type("application/zip").

file_extension

This filter filters documents by their file ending/extension.

Note

  • This Filter only filters by the file ending/extension of the document, it doesn’t check the validity of document.

  • The user can manipulate the file extension of a document and send media with wrong types that don’t fit to this handler.

  • Case insensitive by default, you may change this with the flag case_sensitive=True.

  • Extension should be passed without leading dot unless it’s a part of the extension.

  • Pass None to filter files with no extension, i.e. without a dot in the filename.

Example

  • Filters.document.file_extension("jpg") filters files with extension ".jpg".

  • Filters.document.file_extension(".jpg") filters files with extension "..jpg".

  • Filters.document.file_extension("Dockerfile", case_sensitive=True) filters files with extension ".Dockerfile" minding the case.

  • Filters.document.file_extension(None) filters files without a dot in the filename.

class entity(entity_type)

Bases: telegram.ext.filters.MessageFilter

Filters messages to only allow those which have a telegram.MessageEntity where their type matches entity_type.

Examples

Example MessageHandler(Filters.entity("hashtag"), callback_method)

Parameters

entity_type – Entity type to check for. All types can be found as constants in telegram.MessageEntity.

forwarded = Filters.forwarded

Messages that are forwarded.

class forwarded_from(chat_id=None, username=None, allow_empty=False)

Bases: telegram.ext.filters.Filters._ChatUserBaseFilter

Filters messages to allow only those which are forwarded from the specified chat ID(s) or username(s) based on telegram.Message.forward_from and telegram.Message.forward_from_chat.

New in version 13.5.

Examples

MessageHandler(Filters.forwarded_from(chat_id=1234), callback_method)

Note

When a user has disallowed adding a link to their account while forwarding their messages, this filter will not work since both telegram.Message.forwarded_from and telegram.Message.forwarded_from_chat are None. However, this behaviour is undocumented and might be changed by Telegram.

Warning

chat_ids will give a copy of the saved chat ids as frozenset. This is to ensure thread safety. To add/remove a chat, you should use add_usernames(), add_chat_ids(), remove_usernames() and remove_chat_ids(). Only update the entire set by filter.chat_ids/usernames = new_set, if you are entirely sure that it is not causing race conditions, as this will complete replace the current set of allowed chats.

Parameters
  • chat_id (telegram.utils.types.SLT[int], optional) – Which chat/user ID(s) to allow through.

  • username (telegram.utils.types.SLT[str], optional) – Which username(s) to allow through. Leading '@' s in usernames will be discarded.

  • allow_empty (bool, optional) – Whether updates should be processed, if no chat is specified in chat_ids and usernames. Defaults to False.

Raises

RuntimeError – If both chat_id and username are present.

chat_ids

Which chat/user ID(s) to allow through.

Type

set(int), optional

usernames

Which username(s) (without leading '@') to allow through.

Type

set(str), optional

allow_empty

Whether updates should be processed, if no chat is specified in chat_ids and usernames.

Type

bool, optional

add_chat_ids(chat_id)

Add one or more chats to the allowed chat ids.

Parameters

chat_id (telegram.utils.types.SLT[int], optional) – Which chat/user ID(s) to allow through.

add_usernames(username)

Add one or more chats to the allowed usernames.

Parameters

username (telegram.utils.types.SLT[str], optional) – Which username(s) to allow through. Leading '@' s in usernames will be discarded.

get_chat_or_user(message)
remove_chat_ids(chat_id)

Remove one or more chats from allowed chat ids.

Parameters

chat_id (telegram.utils.types.SLT[int], optional) – Which chat/user ID(s) to disallow through.

remove_usernames(username)

Remove one or more chats from allowed usernames.

Parameters

username (telegram.utils.types.SLT[str], optional) – Which username(s) to disallow through. Leading '@' s in usernames will be discarded.

game = Filters.game

Messages that contain telegram.Game.

group = Filters.group

Messages sent in a group or a supergroup chat.

Note

DEPRECATED. Use telegram.ext.Filters.chat_type.groups instead.

invoice = Filters.invoice

Messages that contain telegram.Invoice.

class language(lang)

Bases: telegram.ext.filters.MessageFilter

Filters messages to only allow those which are from users with a certain language code.

Note

According to official Telegram API documentation, not every single user has the language_code attribute. Do not count on this filter working on all users.

Examples

MessageHandler(Filters.language("en"), callback_method)

Parameters

lang (telegram.utils.types.SLT[str]) – Which language code(s) to allow through. This will be matched using .startswith meaning that ‘en’ will match both ‘en_US’ and ‘en_GB’.

location = Filters.location

Messages that contain telegram.Location.

passport_data = Filters.passport_data

Messages that contain a telegram.PassportData

photo = Filters.photo

Messages that contain telegram.PhotoSize.

poll = Filters.poll

Messages that contain a telegram.Poll.

private = Filters.private

Messages sent in a private chat.

Note

DEPRECATED. Use telegram.ext.Filters.chat_type.private instead.

class regex(pattern)

Bases: telegram.ext.filters.MessageFilter

Filters updates by searching for an occurrence of pattern in the message text. The re.search() function is used to determine whether an update should be filtered.

Refer to the documentation of the re module for more information.

To get the groups and groupdict matched, see telegram.ext.CallbackContext.matches.

Examples

Use MessageHandler(Filters.regex(r'help'), callback) to capture all messages that contain the word ‘help’. You can also use MessageHandler(Filters.regex(re.compile(r'help', re.IGNORECASE)), callback) if you want your pattern to be case insensitive. This approach is recommended if you need to specify flags on your pattern.

Note

Filters use the same short circuiting logic as python’s and, or and not. This means that for example:

>>> Filters.regex(r'(a?x)') | Filters.regex(r'(b?x)')

With a message.text of x, will only ever return the matches for the first filter, since the second one is never evaluated.

Parameters

pattern (str | Pattern) – The regex pattern.

reply = Filters.reply

Messages that are a reply to another message.

class sender_chat(chat_id=None, username=None, allow_empty=False)

Bases: telegram.ext.filters.Filters._ChatUserBaseFilter

Filters messages to allow only those which are from a specified sender chats chat ID or username.

Examples

  • To filter for messages forwarded to a discussion group from a channel with ID -1234, use MessageHandler(Filters.sender_chat(-1234), callback_method).

  • To filter for messages of anonymous admins in a super group with username @anonymous, use MessageHandler(Filters.sender_chat(username='anonymous'), callback_method).

  • To filter for messages forwarded to a discussion group from any channel, use MessageHandler(Filters.sender_chat.channel, callback_method).

  • To filter for messages of anonymous admins in any super group, use MessageHandler(Filters.sender_chat.super_group, callback_method).

Note

Remember, sender_chat is also set for messages in a channel as the channel itself, so when your bot is an admin in a channel and the linked discussion group, you would receive the message twice (once from inside the channel, once inside the discussion group).

Warning

chat_ids will return a copy of the saved chat ids as frozenset. This is to ensure thread safety. To add/remove a chat, you should use add_usernames(), add_chat_ids(), remove_usernames() and remove_chat_ids(). Only update the entire set by filter.chat_ids/usernames = new_set, if you are entirely sure that it is not causing race conditions, as this will complete replace the current set of allowed chats.

Parameters
  • chat_id (telegram.utils.types.SLT[int], optional) – Which sender chat chat ID(s) to allow through.

  • username (telegram.utils.types.SLT[str], optional) – Which sender chat username(s) to allow through. Leading '@' s in usernames will be discarded.

  • allow_empty (bool, optional) – Whether updates should be processed, if no sender chat is specified in chat_ids and usernames. Defaults to False

Raises

RuntimeError – If both chat_id and username are present.

chat_ids

Which sender chat chat ID(s) to allow through.

Type

set(int), optional

usernames

Which sender chat username(s) (without leading '@') to allow through.

Type

set(str), optional

allow_empty

Whether updates should be processed, if no sender chat is specified in chat_ids and usernames.

Type

bool, optional

super_group

Messages whose sender chat is a super group.

Examples

Filters.sender_chat.supergroup

channel

Messages whose sender chat is a channel.

Examples

Filters.sender_chat.channel

add_chat_ids(chat_id)

Add one or more sender chats to the allowed chat ids.

Parameters

chat_id (telegram.utils.types.SLT[int], optional) – Which sender chat ID(s) to allow through.

add_usernames(username)

Add one or more sender chats to the allowed usernames.

Parameters

username (telegram.utils.types.SLT[str], optional) – Which sender chat username(s) to allow through. Leading '@' s in usernames will be discarded.

channel = _Channel
get_chat_or_user(message)
remove_chat_ids(chat_id)

Remove one or more sender chats from allowed chat ids.

Parameters

chat_id (telegram.utils.types.SLT[int], optional) – Which sender chat ID(s) to disallow through.

remove_usernames(username)

Remove one or more sender chats from allowed usernames.

Parameters

username (telegram.utils.types.SLT[str], optional) – Which sender chat username(s) to disallow through. Leading '@' s in usernames will be discarded.

super_group = _SuperGroup
status_update = Filters.status_update

Subset for messages containing a status update.

Examples

Use these filters like: Filters.status_update.new_chat_members etc. Or use just Filters.status_update for all status update messages.

chat_created

Messages that contain telegram.Message.group_chat_created, telegram.Message.supergroup_chat_created or telegram.Message.channel_chat_created.

connected_website

Messages that contain telegram.Message.connected_website.

delete_chat_photo

Messages that contain telegram.Message.delete_chat_photo.

left_chat_member

Messages that contain telegram.Message.left_chat_member.

migrate

Messages that contain telegram.Message.migrate_to_chat_id or telegram.Message.migrate_from_chat_id.

new_chat_members

Messages that contain telegram.Message.new_chat_members.

new_chat_photo

Messages that contain telegram.Message.new_chat_photo.

new_chat_title

Messages that contain telegram.Message.new_chat_title.

message_auto_delete_timer_changed

Messages that contain message_auto_delete_timer_changed.

New in version 13.4.

pinned_message

Messages that contain telegram.Message.pinned_message.

proximity_alert_triggered

Messages that contain telegram.Message.proximity_alert_triggered.

voice_chat_scheduled

Messages that contain telegram.Message.voice_chat_scheduled.

New in version 13.5.

voice_chat_started

Messages that contain telegram.Message.voice_chat_started.

New in version 13.4.

voice_chat_ended

Messages that contain telegram.Message.voice_chat_ended.

New in version 13.4.

voice_chat_participants_invited

Messages that contain telegram.Message.voice_chat_participants_invited.

New in version 13.4.

sticker = Filters.sticker

Messages that contain telegram.Sticker.

successful_payment = Filters.successful_payment

Messages that confirm a telegram.SuccessfulPayment.

text = Filters.text

Text Messages. If a list of strings is passed, it filters messages to only allow those whose text is appearing in the given list.

Examples

To allow any text message, simply use MessageHandler(Filters.text, callback_method).

A simple use case for passing a list is to allow only messages that were sent by a custom telegram.ReplyKeyboardMarkup:

buttons = ['Start', 'Settings', 'Back']
markup = ReplyKeyboardMarkup.from_column(buttons)
...
MessageHandler(Filters.text(buttons), callback_method)

Note

  • Dice messages don’t have text. If you want to filter either text or dice messages, use Filters.text | Filters.dice.

  • Messages containing a command are accepted by this filter. Use Filters.text & (~Filters.command), if you want to filter only text messages without commands.

Parameters

update (List[str] | Tuple[str], optional) – Which messages to allow. Only exact matches are allowed. If not specified, will allow any text message.

update = Filters.update

Subset for filtering the type of update.

Examples

Use these filters like: Filters.update.message or Filters.update.channel_posts etc. Or use just Filters.update for all types.

message

Updates with telegram.Update.message

edited_message

Updates with telegram.Update.edited_message

messages

Updates with either telegram.Update.message or telegram.Update.edited_message

channel_post

Updates with telegram.Update.channel_post

edited_channel_post

Updates with telegram.Update.edited_channel_post

channel_posts

Updates with either telegram.Update.channel_post or telegram.Update.edited_channel_post

class user(user_id=None, username=None, allow_empty=False)

Bases: telegram.ext.filters.Filters._ChatUserBaseFilter

Filters messages to allow only those which are from specified user ID(s) or username(s).

Examples

MessageHandler(Filters.user(1234), callback_method)

Warning

user_ids will give a copy of the saved user ids as frozenset. This is to ensure thread safety. To add/remove a user, you should use add_usernames(), add_user_ids(), remove_usernames() and remove_user_ids(). Only update the entire set by filter.user_ids/usernames = new_set, if you are entirely sure that it is not causing race conditions, as this will complete replace the current set of allowed users.

Parameters
  • user_id (telegram.utils.types.SLT[int], optional) – Which user ID(s) to allow through.

  • username (telegram.utils.types.SLT[str], optional) – Which username(s) to allow through. Leading '@' s in usernames will be discarded.

  • allow_empty (bool, optional) – Whether updates should be processed, if no user is specified in user_ids and usernames. Defaults to False

Raises

RuntimeError – If user_id and username are both present.

user_ids

Which user ID(s) to allow through.

Type

set(int), optional

usernames

Which username(s) (without leading '@') to allow through.

Type

set(str), optional

allow_empty

Whether updates should be processed, if no user is specified in user_ids and usernames.

Type

bool, optional

add_user_ids(user_id)

Add one or more users to the allowed user ids.

Parameters

user_id (telegram.utils.types.SLT[int], optional) – Which user ID(s) to allow through.

add_usernames(username)

Add one or more users to the allowed usernames.

Parameters

username (telegram.utils.types.SLT[str], optional) – Which username(s) to allow through. Leading '@' s in usernames will be discarded.

get_chat_or_user(message)
remove_user_ids(user_id)

Remove one or more users from allowed user ids.

Parameters

user_id (telegram.utils.types.SLT[int], optional) – Which user ID(s) to disallow through.

remove_usernames(username)

Remove one or more users from allowed usernames.

Parameters

username (telegram.utils.types.SLT[str], optional) – Which username(s) to disallow through. Leading '@' s in usernames will be discarded.

property user_ids
venue = Filters.venue

Messages that contain telegram.Venue.

class via_bot(bot_id=None, username=None, allow_empty=False)

Bases: telegram.ext.filters.Filters._ChatUserBaseFilter

Filters messages to allow only those which are from specified via_bot ID(s) or username(s).

Examples

MessageHandler(Filters.via_bot(1234), callback_method)

Warning

bot_ids will give a copy of the saved bot ids as frozenset. This is to ensure thread safety. To add/remove a bot, you should use add_usernames(), add_bot_ids(), remove_usernames() and remove_bot_ids(). Only update the entire set by filter.bot_ids/usernames = new_set, if you are entirely sure that it is not causing race conditions, as this will complete replace the current set of allowed bots.

Parameters
  • bot_id (telegram.utils.types.SLT[int], optional) – Which bot ID(s) to allow through.

  • username (telegram.utils.types.SLT[str], optional) – Which username(s) to allow through. Leading '@' s in usernames will be discarded.

  • allow_empty (bool, optional) – Whether updates should be processed, if no user is specified in bot_ids and usernames. Defaults to False

Raises

RuntimeError – If bot_id and username are both present.

bot_ids

Which bot ID(s) to allow through.

Type

set(int), optional

usernames

Which username(s) (without leading '@') to allow through.

Type

set(str), optional

allow_empty

Whether updates should be processed, if no bot is specified in bot_ids and usernames.

Type

bool, optional

add_bot_ids(bot_id)

Add one or more users to the allowed user ids.

Parameters

bot_id (telegram.utils.types.SLT[int], optional) – Which bot ID(s) to allow through.

add_usernames(username)

Add one or more users to the allowed usernames.

Parameters

username (telegram.utils.types.SLT[str], optional) – Which username(s) to allow through. Leading '@' s in usernames will be discarded.

property bot_ids
get_chat_or_user(message)
remove_bot_ids(bot_id)

Remove one or more users from allowed user ids.

Parameters

bot_id (telegram.utils.types.SLT[int], optional) – Which bot ID(s) to disallow through.

remove_usernames(username)

Remove one or more users from allowed usernames.

Parameters

username (telegram.utils.types.SLT[str], optional) – Which username(s) to disallow through. Leading '@' s in usernames will be discarded.

video = Filters.video

Messages that contain telegram.Video.

video_note = Filters.video_note

Messages that contain telegram.VideoNote.

voice = Filters.voice

Messages that contain telegram.Voice.

class telegram.ext.filters.InvertedFilter(f)

Bases: telegram.ext.filters.UpdateFilter

Represents a filter that has been inverted.

Parameters

f – The filter to invert.

filter(update)

This method must be overwritten.

Parameters

update (telegram.Update) – The update that is tested.

Returns

dict or bool.

class telegram.ext.filters.MergedFilter(base_filter, and_filter=None, or_filter=None)

Bases: telegram.ext.filters.UpdateFilter

Represents a filter consisting of two other filters.

Parameters
  • base_filter – Filter 1 of the merged filter.

  • and_filter – Optional filter to “and” with base_filter. Mutually exclusive with or_filter.

  • or_filter – Optional filter to “or” with base_filter. Mutually exclusive with and_filter.

filter(update)

This method must be overwritten.

Parameters

update (telegram.Update) – The update that is tested.

Returns

dict or bool.

class telegram.ext.filters.MessageFilter

Bases: telegram.ext.filters.BaseFilter, abc.ABC

Base class for all Message Filters. In contrast to UpdateFilter, the object passed to filter() is update.effective_message.

Please see telegram.ext.filters.BaseFilter for details on how to create custom filters.

name

Name for this filter. Defaults to the type of filter.

Type

str

data_filter

Whether this filter is a data filter. A data filter should return a dict with lists. The dict will be merged with telegram.ext.CallbackContext’s internal dict in most cases (depends on the handler).

Type

bool

abstract filter(message)

This method must be overwritten.

Parameters

message (telegram.Message) – The message that is tested.

Returns

dict or bool

class telegram.ext.filters.UpdateFilter

Bases: telegram.ext.filters.BaseFilter, abc.ABC

Base class for all Update Filters. In contrast to MessageFilter, the object passed to filter() is update, which allows to create filters like Filters.update.edited_message.

Please see telegram.ext.filters.BaseFilter for details on how to create custom filters.

name

Name for this filter. Defaults to the type of filter.

Type

str

data_filter

Whether this filter is a data filter. A data filter should return a dict with lists. The dict will be merged with telegram.ext.CallbackContext’s internal dict in most cases (depends on the handler).

Type

bool

abstract filter(update)

This method must be overwritten.

Parameters

update (telegram.Update) – The update that is tested.

Returns

dict or bool.

class telegram.ext.filters.XORFilter(base_filter, xor_filter)

Bases: telegram.ext.filters.UpdateFilter

Convenience filter acting as wrapper for MergedFilter representing the an XOR gate for two filters.

Parameters
  • base_filter – Filter 1 of the merged filter.

  • xor_filter – Filter 2 of the merged filter.

filter(update)

This method must be overwritten.

Parameters

update (telegram.Update) – The update that is tested.

Returns

dict or bool.