Hide navigation sidebar
Hide table of contents sidebar
PTB has undergone significant changes in v20. Please read the documentation carefully and also check out the transition guide in the wiki.
Back to top
Toggle table of contents sidebar

# CallbackQueryHandler

class telegram.ext.CallbackQueryHandler(callback, 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`.

    New in version 13.6.

  Warning

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

  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.

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

  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`

  Available In

  `telegram.ext.Application.handlers`

  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.