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¶

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

Type:	`str`

update_filter¶

Whether this filter should work on update. If False it will run the filter on update.effective_message`. Default is False.

Type:	`bool`

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`

filter(update)¶

This method must be overwritten.

Note

If update_filter is false then the first argument is message and of type telegram.Message.

Parameters:	update (`telegram.Update`) – The update that is tested.
Returns:	`dict` or `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.

Type:	`Filter`

animation = Filters.animation¶

Messages that contain telegram.Animation.

Type:	`Filter`

audio = Filters.audio¶

Messages that contain telegram.Audio.

Type:	`Filter`

class caption_entity(entity_type)¶

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`.

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.

command = Filters.command¶

Messages starting with /.

Type:	`Filter`

contact = Filters.contact¶

Messages that contain telegram.Contact.

Type:	`Filter`

document = Filters.document¶

Messages that contain telegram.Document.

Type:	`Filter`

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`.

forwarded = Filters.forwarded¶

Messages that are forwarded.

Type:	`Filter`

game = Filters.game¶

Messages that contain telegram.Game.

Type:	`Filter`

group = Filters.group¶

Messages sent in a group chat.

Type:	`Filter`

invoice = Filters.invoice¶

Messages that contain telegram.Invoice.

Type:	`Filter`

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’.

location = Filters.location¶

Messages that contain telegram.Location.

Type:	`Filter`

passport_data = Filters.passport_data¶

Messages that contain a telegram.PassportData

Type:	`Filter`

photo = Filters.photo¶

Messages that contain telegram.PhotoSize.

Type:	`Filter`

private = Filters.private¶

Messages sent in a private chat.

Type:	`Filter`

class regex(pattern)¶

Bases: telegram.ext.filters.BaseFilter

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.

Parameters:	pattern (`str` \| `Pattern`) – The regex pattern.

reply = Filters.reply¶

Messages that are a reply to another message.

Type:	`Filter`

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.

Type:	`Filter`

delete_chat_photo¶

Messages that contain telegram.Message.delete_chat_photo.

Type:	`Filter`

left_chat_member¶

Messages that contain telegram.Message.left_chat_member.

Type:	`Filter`

migrate¶

Messages that contain telegram.Message.migrate_from_chat_id or :attr: telegram.Message.migrate_from_chat_id.

Type:	`Filter`

new_chat_members¶

Messages that contain telegram.Message.new_chat_members.

Type:	`Filter`

new_chat_photo¶

Messages that contain telegram.Message.new_chat_photo.

Type:	`Filter`

new_chat_title¶

Messages that contain telegram.Message.new_chat_title.

Type:	`Filter`

pinned_message¶

Messages that contain telegram.Message.pinned_message.

Type:	`Filter`

sticker = Filters.sticker¶

Messages that contain telegram.Sticker.

Type:	`Filter`

successful_payment = Filters.successful_payment¶

Messages that confirm a telegram.SuccessfulPayment.

Type:	`Filter`

text = Filters.text¶

Text Messages.

Type:	`Filter`

update = _UpdateType¶

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

Type:	`Filter`

edited_message¶

Updates with telegram.Update.edited_message

Type:	`Filter`

messages¶

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

Type:	`Filter`

channel_post¶

Updates with telegram.Update.channel_post

Type:	`Filter`

edited_channel_post¶

Updates with telegram.Update.edited_channel_post

Type:	`Filter`

channel_posts¶

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

Type:	`Filter`

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.

venue = Filters.venue¶

Messages that contain telegram.Venue.

Type:	`Filter`

video = Filters.video¶

Messages that contain telegram.Video.

Type:	`Filter`

video_note = Filters.video_note¶

Messages that contain telegram.VideoNote.

Type:	`Filter`

voice = Filters.voice¶

Messages that contain telegram.Voice.

Type:	`Filter`

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(update)¶

This method must be overwritten.

Note

If update_filter is false then the first argument is message and of type telegram.Message.

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.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(update)¶

This method must be overwritten.

Note

If update_filter is false then the first argument is message and of type telegram.Message.

Parameters:	update (`telegram.Update`) – The update that is tested.
Returns:	`dict` or `bool`