CallbackQueryHandler

class telegram.ext.CallbackQueryHandler(callback, pattern=None, game_pattern=None, block=True)

Bases: telegram.ext.BaseHandler

Handler class to handle Telegram callback queries. Optionally based on a regex.

Read the documentation of the re module for more information.

Note

• If your bot allows arbitrary objects as callback_data, it may happen that the original callback_data for the incoming telegram.CallbackQuery can not be found. This is the case when either a malicious client tempered with the telegram.CallbackQuery.data or the data was simply dropped from cache or not persisted. In these cases, an instance of telegram.ext.InvalidCallbackData will be set as telegram.CallbackQuery.data.

  Added in version 13.6.

• If neither pattern nor game_pattern is set, any CallbackQuery will be handled. If only pattern is set, queries with game_short_name will not be considered and vice versa. If both patterns are set, queries with either :attr: ~telegram.CallbackQuery.game_short_name or data matching the defined pattern will be handled

  Added in version 21.5.

Warning

When setting block to False, you cannot rely on adding custom attributes to telegram.ext.CallbackContext. See its docs for more info.

Available In

telegram.ext.Application.handlers

Parameters:

• callback (coroutine function) –

  The callback function for this handler. Will be called when check_update() has determined that an update should be processed by this handler. Callback signature:

  async def callback(update: Update, context: CallbackContext)
  

  The return value of the callback is usually ignored except for the special case of telegram.ext.ConversationHandler.

• pattern (str | re.Pattern | callable | type, optional) –

  Pattern to test telegram.CallbackQuery.data against. If a string or a regex pattern is passed, re.match() is used on telegram.CallbackQuery.data to determine if an update should be handled by this handler. If your bot allows arbitrary objects as callback_data, non-strings will be accepted. To filter arbitrary objects you may pass:

  • a callable, accepting exactly one argument, namely the telegram.CallbackQuery.data. It must return True or False/None to indicate, whether the update should be handled.

  • a type. If telegram.CallbackQuery.data is an instance of that type (or a subclass), the update will be handled.

  If telegram.CallbackQuery.data is None, the telegram.CallbackQuery update will not be handled.

  See also

  Arbitrary callback_data

  Changed in version 13.6: Added support for arbitrary callback data.

• game_pattern (str | re.Pattern | optional) –

  Pattern to test telegram.CallbackQuery.game_short_name against. If a string or a regex pattern is passed, re.match() is used on telegram.CallbackQuery.game_short_name to determine if an update should be handled by this handler.

  Added in version 21.5.

• block (bool, optional) –

  Determines whether the return value of the callback should be awaited before processing the next handler in telegram.ext.Application.process_update(). Defaults to True.

  See also

  Concurrency

callback

The callback function for this handler.

Type:

coroutine function

pattern

Optional. Regex pattern, callback or type to test telegram.CallbackQuery.data against.

Changed in version 13.6: Added support for arbitrary callback data.

Type:

re.Pattern | callable | type

game_pattern

Optional. Regex pattern to test telegram.CallbackQuery.game_short_name

Type:

re.Pattern

block

Determines whether the return value of the callback should be awaited before processing the next handler in telegram.ext.Application.process_update().

Type:

bool

check_update(update)

Determines whether an update should be passed to this handler’s callback.

Parameters:

update (telegram.Update | object) – Incoming update.

Returns:

bool

collect_additional_context(context, update, application, check_result)

Add the result of re.match(pattern, update.callback_query.data) to CallbackContext.matches as list with one element.