OpenSource/python-telegram-bot
OpenSource/python-telegram-bot
1
0
Fork 0
mirror of https://github.com/python-telegram-bot/python-telegram-bot.git synced 2024-11-21 14:46:29 +01:00
Code Issues Projects Releases Packages Wiki Activity
Page: Extensions Advanced Filters
Pages
Adding defaults to your bot Arbitrary callback_data Architecture Ask Right Ask Support Avoiding flood limits Bot API Forward Compatibility Bots built with PTB Builder Pattern Code snippets Concurrency Emoji Examples Exception Handling Exceptions, Warnings and Logging Extensions Advanced Filters Extensions JobQueue Extensions Your first Bot Extensions – Advanced Filters Extensions – JobQueue Extensions – Your first Bot Frequently Asked Questions Frequently requested design patterns Handling network errors Home Hosting your bot InlineKeyboard Example Internal test bots Introduction to the API Local Bot API Server MWE Making your bot persistent Notes about GAE Google App Engine PTB test writing knowledge base Performance Optimizations Press Project Bots, Groups and Channels Related Projects Storing bot, user and chat related data Storing user and chat related data Telegram Passport Transition guide to Version 12.0 Transition guide to Version 13.0 Transition guide to Version 20.0 Transition guide to Version 4.0 Transition guide to Version 5.0 Type Checking Types of Handlers Webhooks Where to host Telegram Bots Working Behind a Proxy Working with Files and Media Writing Tests
4 Extensions Advanced Filters
Harshil edited this page 2023-12-15 18:11:50 +04:00
Table of Contents

This page describes advanced use cases for the filters used with MessageHandler (also with CommandHandler and PrefixHandler) from telegram.ext.

Combining filters

When using MessageHandler it is sometimes useful to have more than one filter. This can be done using so called bit-wise operators. In Python those operators are &, | and ~ meaning AND, OR and NOT respectively. Since version 13.1 filters support ^ for XOR.

Examples

Message is either video, photo, or document (generic file)

from telegram.ext import MessageHandler, filters

handler = MessageHandler(
   filters.VIDEO | filters.PHOTO | filters.Document.ALL, 
   callback
)

Message is a forwarded photo

handler = MessageHandler(filters.FORWARDED & filters.PHOTO, callback)

Message is text and contains a link

from telegram import MessageEntity

handler = MessageHandler(
   filters.TEXT & (
      filters.Entity(MessageEntity.URL) |
      filters.Entity(MessageEntity.TEXT_LINK)
   ),
   callback
)

Message is a photo and it's not forwarded

handler = MessageHandler(
   filters.PHOTO & (~ filters.FORWARDED),
   callback
)

Custom filters

It is also possible to write our own filters. In essence, a filter is simply a function that receives either a Message instance or a Update instance and returns either True or False. This function has to be implemented in a new class that inherits from either MessageFilter or UpdateFilter, which allows it to be combined with other filters. If the combination of all filters evaluates to True, the message will be handled.

The difference between UpdateFilter and MessageFilter is that the filter function of the former will receive the update, allowing e.g. to differentiate between channel post updates and message updates, while the filter function of the latter will receive the update.effective_message.

Say we wanted to allow only those messages that contain the text "python-telegram-bot is awesome", we could write a custom filter as so:

from telegram.ext.filters import MessageFilter

class FilterAwesome(MessageFilter):
    def filter(self, message):
        return 'python-telegram-bot is awesome' in message.text

# Remember to initialize the class.
filter_awesome = FilterAwesome()

The class can of course be named however you want, the only important things are:

  • The class has to inherit from MessageFilter or UpdateFilter
  • It has to implement a filter method
  • You have to create an instance of the class

The filter can then be used as:

awesome_handler = MessageHandler(filter_awesome, callback)
application.add_handler(awesome_handler)

Filters and CallbackContext

You may have noticed that when using filters.Regex, the attributes context.matches and context.match are set to the corresponding matches. To achieve something like this for your custom filter, you can do the following:

  1. Set self.data_filter=True for your filter.
  2. If the update should be handled, return a dictionary of the form {attribute_name: [values]}. This dict will be merged with the internal dict of the context argument making value available as context.attribute_name. This currently works with MessageHandler, CommandHandler and PrefixHandler, which are the only handlers that accept filters.

Important

The values of the returned dict must be lists. This is necessary to make sure that multiple data filters can be merged meaningfully.

If you want this to work with your custom handler, make sure that YourHandler.collect_additional_context does something like

if isinstance(check_result, dict):
    context.update(check_result)

Must read

  1. Introduction to the API
  2. Tutorial: Your first bot
  3. FAQ
  4. How to ask good questions
  5. How to write an MWE

Concepts & Important Elements

  1. Architecture Overview
  2. Builder Pattern for Application
  3. Types of Handlers
  4. Working with Files and Media
  5. Exceptions, Warnings and Logging
  6. Concurrency in PTB

Notable Features

  1. Advanced Filters
  2. Storing data
  3. Making your bot persistent
  4. Adding Defaults
  5. Job Queue
  6. Arbitrary callback_data
  7. Avoiding flood limits
  8. Webhooks
  9. Bot API Forward Compatiblity

Code Resources

  1. Frequently requested design patterns
  2. Code snippets
  3. Performance Optimizations
  4. Telegram Passport
  5. Bots built with PTB
  6. Automated Bot Tests

Examples explained

  1. InlineKeyboard Example

Networking

  1. Working Behind a Proxy
  2. Handling network errors

Other resources

  1. Where to host Telegram Bots
  2. How to host your bot
  3. Local API Server
  4. Type Checking with PTB
  5. Press
  6. Notes on GAE
  7. Related Projects
  8. Emoji

Transition Guides

Administration