telegram.ext.filters Module¶
This module contains the Filters for use with the MessageHandler class.
-
class
telegram.ext.filters.
BaseFilter
¶ Bases:
object
Base class for all Message Filters.
Subclassing from this class filters to be combined using bitwise operators:
And:
>>> (Filters.text & Filters.entity(MENTION))
Or:
>>> (Filters.audio | Filters.video)
Not:
>>> ~ Filters.command
Also works with more than two filters:
>>> (Filters.text & (Filters.entity(URL) | Filters.entity(TEXT_LINK))) >>> Filters.text & (~ Filters.forwarded)
If you want to create your own filters create a class inheriting from this class 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
¶ str
– Name for this filter. Defaults to the type of filter.
-
filter
(message)¶ This method must be overwritten.
Parameters: message ( telegram.Message
) – The message that is tested.Returns: 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. UseMessageHandler(Filters.contact, callback_method)
for all contacts. etc.-
all
= Filters.all¶ Filter
– All Messages.
-
animation
= Filters.animation¶ Filter
– Messages that containtelegram.Animation
.
-
audio
= Filters.audio¶ Filter
– Messages that containtelegram.Audio
.
Bases:
telegram.ext.filters.BaseFilter
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
.This method must be overwritten.
Parameters: message ( telegram.Message
) – The message that is tested.Returns: bool
-
class
chat
(chat_id=None, username=None)¶ Bases:
telegram.ext.filters.BaseFilter
Filters messages to allow only those which are from specified chat ID.
Examples
MessageHandler(Filters.chat(-1234), callback_method)
Parameters: - chat_id (
int
| List[int
], optional) – Which chat ID(s) to allow through. - username (
str
| List[str
], optional) – Which username(s) to allow through. If username start swith ‘@’ symbol, it will be ignored.
Raises: ValueError
– If chat_id and username are both present, or neither is.-
filter
(message)¶ This method must be overwritten.
Parameters: message ( telegram.Message
) – The message that is tested.Returns: bool
- chat_id (
-
command
= Filters.command¶ Filter
– Messages starting with/
.
-
contact
= Filters.contact¶ Filter
– Messages that containtelegram.Contact
.
-
document
= Filters.document¶ Filter
– Messages that containtelegram.Document
.
-
class
entity
(entity_type)¶ Bases:
telegram.ext.filters.BaseFilter
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
.-
filter
(message)¶ This method must be overwritten.
Parameters: message ( telegram.Message
) – The message that is tested.Returns: bool
-
-
forwarded
= Filters.forwarded¶ Filter
– Messages that are forwarded.
-
game
= Filters.game¶ Filter
– Messages that containtelegram.Game
.
-
group
= Filters.group¶ Filter
– Messages sent in a group chat.
-
invoice
= Filters.invoice¶ Filter
– Messages that containtelegram.Invoice
.
-
class
language
(lang)¶ Bases:
telegram.ext.filters.BaseFilter
Filters messages to only allow those which are from users with a certain language code.
Note: According to telegrams documentation, every single user does not have the language_code attribute.
Examples
MessageHandler(Filters.language("en"), callback_method)
Parameters: lang ( str
| List[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’.-
filter
(message)¶ This method must be overwritten.
Parameters: message ( telegram.Message
) – The message that is tested.Returns: bool
-
-
location
= Filters.location¶ Filter
– Messages that containtelegram.Location
.
-
passport_data
= Filters.passport_data¶ Filter
– Messages that contain atelegram.PassportData
-
photo
= Filters.photo¶ Filter
– Messages that containtelegram.PhotoSize
.
-
private
= Filters.private¶ Filter
– Messages sent in a private chat.
-
class
regex
(pattern)¶ Bases:
telegram.ext.filters.BaseFilter
Filters updates by searching for an occurence of
pattern
in the message text. There.search
function is used to determine whether an update should be filtered. Refer to the documentation of there
module for more information.Note: Does not allow passing groups or a groupdict like the
RegexHandler
yet, but this will probably be implemented in a future update, gradually phasing out the RegexHandler (see https://github.com/python-telegram-bot/python-telegram-bot/issues/835).Examples
Example
CommandHandler("start", deep_linked_callback, Filters.regex('parameter'))
Parameters: pattern ( str
|Pattern
) – The regex pattern.-
filter
(message)¶ This method must be overwritten.
Parameters: message ( telegram.Message
) – The message that is tested.Returns: bool
-
-
reply
= Filters.reply¶ Filter
– Messages that are a reply to another message.
-
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 justFilters.status_update
for all status update messages.-
chat_created
¶ Filter
– Messages that containtelegram.Message.group_chat_created
,telegram.Message.supergroup_chat_created
ortelegram.Message.channel_chat_created
.
-
delete_chat_photo
¶ Filter
– Messages that containtelegram.Message.delete_chat_photo
.
-
left_chat_member
¶ Filter
– Messages that containtelegram.Message.left_chat_member
.
-
migrate
¶ Filter
– Messages that containtelegram.Message.migrate_from_chat_id
or :attr: telegram.Message.migrate_from_chat_id.
-
new_chat_members
¶ Filter
– Messages that containtelegram.Message.new_chat_members
.
-
new_chat_photo
¶ Filter
– Messages that containtelegram.Message.new_chat_photo
.
-
new_chat_title
¶ Filter
– Messages that containtelegram.Message.new_chat_title
.
-
pinned_message
¶ Filter
– Messages that containtelegram.Message.pinned_message
.
-
-
sticker
= Filters.sticker¶ Filter
– Messages that containtelegram.Sticker
.
-
successful_payment
= Filters.successful_payment¶ Filter
– Messages that confirm atelegram.SuccessfulPayment
.
-
text
= Filters.text¶ Filter
– Text Messages.
-
class
user
(user_id=None, username=None)¶ Bases:
telegram.ext.filters.BaseFilter
Filters messages to allow only those which are from specified user ID.
Examples
MessageHandler(Filters.user(1234), callback_method)
Parameters: - user_id (
int
| List[int
], optional) – Which user ID(s) to allow through. - username (
str
| List[str
], optional) – Which username(s) to allow through. If username starts with ‘@’ symbol, it will be ignored.
Raises: ValueError
– If chat_id and username are both present, or neither is.-
filter
(message)¶ This method must be overwritten.
Parameters: message ( telegram.Message
) – The message that is tested.Returns: bool
- user_id (
-
venue
= Filters.venue¶ Filter
– Messages that containtelegram.Venue
.
-
video
= Filters.video¶ Filter
– Messages that containtelegram.Video
.
-
video_note
= Filters.video_note¶ Filter
– Messages that containtelegram.VideoNote
.
-
voice
= Filters.voice¶ Filter
– Messages that containtelegram.Voice
.
-
-
class
telegram.ext.filters.
InvertedFilter
(f)¶ Bases:
telegram.ext.filters.BaseFilter
Represents a filter that has been inverted.
Parameters: f – The filter to invert. -
filter
(message)¶ This method must be overwritten.
Parameters: message ( telegram.Message
) – The message that is tested.Returns: bool
-
-
class
telegram.ext.filters.
MergedFilter
(base_filter, and_filter=None, or_filter=None)¶ Bases:
telegram.ext.filters.BaseFilter
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
(message)¶ This method must be overwritten.
Parameters: message ( telegram.Message
) – The message that is tested.Returns: bool