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. Use MessageHandler(Filters.contact, callback_method) for all contacts. etc.

all = Filters.all

Filter – All Messages.

audio = Filters.audio

Filter – Messages that contain telegram.Audio.

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

Filter – Messages starting with /.

contact = Filters.contact

Filter – Messages that contain telegram.Contact.

document = Filters.document

Filter – Messages that contain telegram.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.
forwarded = Filters.forwarded

Filter – Messages that are forwarded.

game = Filters.game

Filter – Messages that contain telegram.Game.

group = Filters.group

Filter – Messages sent in a group chat.

invoice = Filters.invoice

Filter – Messages that contain telegram.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’.
location = Filters.location

Filter – Messages that contain telegram.Location.

photo = Filters.photo

Filter – Messages that contain telegram.PhotoSize.

private = Filters.private

Filter – Messages sent in a private chat.

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_member etc. Or use just Filters.status_update for all status update messages.

chat_created

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

delete_chat_photo

Filter – Messages that contain telegram.Message.delete_chat_photo.

left_chat_member

Filter – Messages that contain telegram.Message.left_chat_member.

migrate

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

new_chat_members

Filter – Messages that contain telegram.Message.new_chat_member.

new_chat_photo

Filter – Messages that contain telegram.Message.new_chat_photo.

new_chat_title

Filter – Messages that contain telegram.Message.new_chat_title.

pinned_message

Filter – Messages that contain telegram.Message.pinned_message.

sticker = Filters.sticker

Filter – Messages that contain telegram.Sticker.

successful_payment = Filters.successful_payment

Filter – Messages that confirm a telegram.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.

venue = Filters.venue

Filter – Messages that contain telegram.Venue.

video = Filters.video

Filter – Messages that contain telegram.Video.

voice = Filters.voice

Filter – Messages that contain telegram.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.
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.