CallbackContext¶
- class telegram.ext.CallbackContext(application, chat_id=None, user_id=None)[source]¶
This is a context object passed to the callback called by
telegram.ext.BaseHandler
or by thetelegram.ext.Application
in an error handler added bytelegram.ext.Application.add_error_handler
or to the callback of atelegram.ext.Job
.Note
telegram.ext.Application
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 receive the sameCallbackContext
object (of course with proper attributes likematches
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 onCallbackContext
might change in the future, so make sure to use a fairly unique name for the attributes.Warning
Do not combine custom attributes with
telegram.ext.BaseHandler.block
set toFalse
ortelegram.ext.Application.concurrent_updates
set toTrue
. Due to how those work, 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.This class is a
Generic
class and accepts four type variables:The type of
bot
. Must betelegram.Bot
or a subclass of that class.
Examples
- Parameters:
application (
telegram.ext.Application
) – The application associated with this context.The ID of the chat associated with this object. Used to provide
chat_data
.Added in version 20.0.
The ID of the user associated with this object. Used to provide
user_data
.Added in version 20.0.
- coroutine[source]¶
Optional. Only present in error handlers if the error was caused by an awaitable run with
Application.create_task()
or a handler callback withblock=False
.- Type:
- matches[source]¶
Optional. If the associated update originated from a
filters.Regex
, this will contain a list of match objects for every pattern wherere.search(pattern, string)
returned a match. Note that filters short circuit, so combined regex filters will not always be evaluated.- Type:
list[
re.Match
]
- args[source]¶
Optional. Arguments passed to a command if the associated update is handled by
telegram.ext.CommandHandler
,telegram.ext.PrefixHandler
ortelegram.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[source]¶
Optional. The error that was raised. Only present when passed to an error handler registered with
telegram.ext.Application.add_error_handler
.- Type:
- job[source]¶
Optional. The job which originated this callback. Only present when passed to the callback of
telegram.ext.Job
or in error handlers if the error is caused by a job.Changed in version 20.0:
job
is now also present in error handlers if the error is caused by a job.- Type:
- property bot_data[source]¶
Optional. An object that can be used to keep any data in. For each update it will be the same
ContextTypes.bot_data
. Defaults todict
.- Type:
- property chat_data[source]¶
Optional. An object that can be used to keep any data in. For each update from the same chat id it will be the same
ContextTypes.chat_data
. Defaults todict
.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.Changed in version 20.0: The chat data is now also present in error handlers if the error is caused by a job.
- Type:
- drop_callback_data(callback_query)[source]¶
Deletes the cached data for the specified callback query.
Added 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.See also
- Parameters:
callback_query (
telegram.CallbackQuery
) – The callback query.- Raises:
KeyError | RuntimeError –
KeyError
, if the callback query can not be found in the cache andRuntimeError
, if the bot doesn’t allow for arbitrary callback data.
- classmethod from_error(update, error, application, job=None, coroutine=None)[source]¶
Constructs an instance of
telegram.ext.CallbackContext
to be passed to the error handlers.Changed in version 20.0: Removed arguments
async_args
andasync_kwargs
.- Parameters:
update (
object
|telegram.Update
) – The update associated with the error. May beNone
, e.g. for errors in job callbacks.application (
telegram.ext.Application
) – The application associated with this context.job (
telegram.ext.Job
, optional) –The job associated with the error.
Added in version 20.0.
coroutine (awaitable, optional) –
The awaitable associated with this error if the error was caused by a coroutine run with
Application.create_task()
or a handler callback withblock=False
.Added in version 20.0.
Changed in version 20.2: Accepts
asyncio.Future
and generator-based coroutine functions.
- Returns:
- classmethod from_job(job, application)[source]¶
Constructs an instance of
telegram.ext.CallbackContext
to be passed to a job callback.See also
- Parameters:
job (
telegram.ext.Job
) – The job.application (
telegram.ext.Application
) – The application associated with this context.
- Returns:
- classmethod from_update(update, application)[source]¶
Constructs an instance of
telegram.ext.CallbackContext
to be passed to the handlers.- Parameters:
update (
object
|telegram.Update
) – The update.application (
telegram.ext.Application
) – The application associated with this context.
- Returns:
- property job_queue[source]¶
The
JobQueue
used by thetelegram.ext.Application
.See also
- Type:
- property match[source]¶
The first match from
matches
. Useful if you are only filtering using a single regex filter. ReturnsNone
ifmatches
is empty.- Type:
- async refresh_data()[source]¶
If
application
uses persistence, callstelegram.ext.BasePersistence.refresh_bot_data()
onbot_data
,telegram.ext.BasePersistence.refresh_chat_data()
onchat_data
andtelegram.ext.BasePersistence.refresh_user_data()
onuser_data
, if appropriate.Will be called by
telegram.ext.Application.process_update()
andtelegram.ext.Job.run()
.Added in version 13.6.
- property update_queue[source]¶
The
asyncio.Queue
instance used by thetelegram.ext.Application
and (usually) thetelegram.ext.Updater
associated with this context.- Type:
- property user_data[source]¶
Optional. An object that can be used to keep any data in. For each update from the same user it will be the same
ContextTypes.user_data
. Defaults todict
.Changed in version 20.0: The user data is now also present in error handlers if the error is caused by a job.
- Type: