Skip to content
Back to top
View this page

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

  Use In

  - `telegram.ext.Application.add_handler()`

  - `telegram.ext.Application.add_handlers()`

  - `telegram.ext.Application.remove_handler()`

  Available In

  - `telegram.ext.ConversationHandler.entry_points`

  - `telegram.ext.ConversationHandler.fallbacks`

  - `telegram.ext.ConversationHandler.states`

  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.