telegram.ext.CallbackContext

class telegram.ext.CallbackContext(dispatcher)

This is a context object passed to the callback called by telegram.ext.Handler or by the telegram.ext.Dispatcher in an error handler added by telegram.ext.Dispatcher.add_error_handler or to the callback of a telegram.ext.Job.

Note

telegram.ext.Dispatcher will create a single context for an entire update. This means that if you got 2 handlers in different groups and they both get called, they will get passed the same CallbackContext object (of course with proper attributes like .matches differing). This allows you to add custom attributes in a lower handler group callback, and then subsequently access those attributes in a higher handler group callback. Note that the attributes on CallbackContext might change in the future, so make sure to use a fairly unique name for the attributes.

Warning

Do not combine custom attributes and @run_async/ telegram.ext.Disptacher.run_async(). Due to how run_async works, it will almost certainly execute the callbacks for an update out of order, and the attributes that you think you added will not be present.

Parameters

dispatcher (telegram.ext.Dispatcher) – The dispatcher associated with this context.

matches

Optional. If the associated update originated from a regex-supported handler or had a Filters.regex, this will contain a list of match objects for every pattern where re.search(pattern, string) returned a match. Note that filters short circuit, so combined regex filters will not always be evaluated.

Type

List[re match object]

args

Optional. Arguments passed to a command if the associated update is handled by telegram.ext.CommandHandler, telegram.ext.PrefixHandler or telegram.ext.StringCommandHandler. It contains a list of the words in the text after the command, using any whitespace string as a delimiter.

Type

List[str]

error

Optional. The error that was raised. Only present when passed to a error handler registered with telegram.ext.Dispatcher.add_error_handler.

Type

Exception

async_args

Optional. Positional arguments of the function that raised the error. Only present when the raising function was run asynchronously using telegram.ext.Dispatcher.run_async().

Type

List[object]

async_kwargs

Optional. Keyword arguments of the function that raised the error. Only present when the raising function was run asynchronously using telegram.ext.Dispatcher.run_async().

Type

Dict[str, object]

job

Optional. The job which originated this callback. Only present when passed to the callback of telegram.ext.Job.

Type

telegram.ext.Job

property bot

The bot associated with this context.

Type

telegram.Bot

property bot_data

Optional. A dict that can be used to keep any data in. For each update it will be the same dict.

Type

dict

property chat_data

Optional. A dict that can be used to keep any data in. For each update from the same chat id it will be the same dict.

Warning

When a group chat migrates to a supergroup, its chat id will change and the chat_data needs to be transferred. For details see our wiki page.

Type

dict

property dispatcher

The dispatcher associated with this context.

Type

telegram.ext.Dispatcher

drop_callback_data(callback_query)

Deletes the cached data for the specified callback query.

New in version 13.6.

Note

Will not raise exceptions in case the data is not found in the cache. Will raise KeyError in case the callback query can not be found in the cache.

Parameters

callback_query (telegram.CallbackQuery) – The callback query.

Raises

KeyError | RuntimeErrorKeyError, if the callback query can not be found in the cache and RuntimeError, if the bot doesn’t allow for arbitrary callback data.

classmethod from_error(update, error, dispatcher, async_args=None, async_kwargs=None)

Constructs an instance of telegram.ext.CallbackContext to be passed to the error handlers.

Parameters
  • update (object | telegram.Update) – The update associated with the error. May be None, e.g. for errors in job callbacks.

  • error (Exception) – The error.

  • dispatcher (telegram.ext.Dispatcher) – The dispatcher associated with this context.

  • async_args (List[object]) – Optional. Positional arguments of the function that raised the error. Pass only when the raising function was run asynchronously using telegram.ext.Dispatcher.run_async().

  • async_kwargs (Dict[str, object]) – Optional. Keyword arguments of the function that raised the error. Pass only when the raising function was run asynchronously using telegram.ext.Dispatcher.run_async().

Returns

telegram.ext.CallbackContext

classmethod from_job(job, dispatcher)

Constructs an instance of telegram.ext.CallbackContext to be passed to a job callback.

Parameters
Returns

telegram.ext.CallbackContext

classmethod from_update(update, dispatcher)

Constructs an instance of telegram.ext.CallbackContext to be passed to the handlers.

Parameters
Returns

telegram.ext.CallbackContext

property job_queue

The JobQueue used by the telegram.ext.Dispatcher and (usually) the telegram.ext.Updater associated with this context.

Type

telegram.ext.JobQueue

property match

The first match from matches. Useful if you are only filtering using a single regex filter. Returns None if matches is empty.

Type

Regex match type

refresh_data()

If dispatcher uses persistence, calls telegram.ext.BasePersistence.refresh_bot_data() on bot_data, telegram.ext.BasePersistence.refresh_chat_data() on chat_data and telegram.ext.BasePersistence.refresh_user_data() on user_data, if appropriate.

New in version 13.6.

update(data)

Updates self.__slots__ with the passed data.

Parameters

data (Dict[str, object]) – The data.

property update_queue

The Queue instance used by the telegram.ext.Dispatcher and (usually) the telegram.ext.Updater associated with this context.

Type

queue.Queue

property user_data

Optional. A dict that can be used to keep any data in. For each update from the same user it will be the same dict.

Type

dict