telegram.ext.Updater¶
-
class
telegram.ext.
Updater
(token=None, base_url=None, workers=4, bot=None, private_key=None, private_key_password=None, user_sig_handler=None, request_kwargs=None, persistence=None, defaults=None, use_context=True, dispatcher=None, base_file_url=None, arbitrary_callback_data=False, context_types=None)¶ Bases:
Generic
[telegram.ext.utils.types.CCT
,telegram.ext.utils.types.UD
,telegram.ext.utils.types.CD
,telegram.ext.utils.types.BD
]This class, which employs the
telegram.ext.Dispatcher
, provides a frontend totelegram.Bot
to the programmer, so they can focus on coding the bot. Its purpose is to receive the updates from Telegram and to deliver them to said dispatcher. It also runs in a separate thread, so the user can interact with the bot, for example on the command line. The dispatcher supports handlers for different kinds of data: Updates from Telegram, basic text commands and even arbitrary types. The updater can be started as a polling service or, for production, use a webhook to receive updates. This is achieved using the WebhookServer and WebhookHandler classes.Note
You must supply either a
bot
or atoken
argument.If you supply a
bot
, you will need to passarbitrary_callback_data
, anddefaults
to the bot instead of thetelegram.ext.Updater
. In this case, you’ll have to use the classtelegram.ext.ExtBot
.Changed in version 13.6.
- Parameters
token (
str
, optional) – The bot’s token given by the @BotFather.base_url (
str
, optional) – Base_url for the bot.base_file_url (
str
, optional) – Base_file_url for the bot.workers (
int
, optional) – Amount of threads in the thread pool for functions decorated with@run_async
(ignored if dispatcher argument is used).bot (
telegram.Bot
, optional) – A pre-initialized bot instance (ignored if dispatcher argument is used). If a pre-initialized bot is used, it is the user’s responsibility to create it using a Request instance with a large enough connection pool.dispatcher (
telegram.ext.Dispatcher
, optional) – A pre-initialized dispatcher instance. If a pre-initialized dispatcher is used, it is the user’s responsibility to create it with proper arguments.private_key (
bytes
, optional) – Private key for decryption of telegram passport data.private_key_password (
bytes
, optional) – Password for above private key.user_sig_handler (
function
, optional) – Takessignum, frame
as positional arguments. This will be called when a signal is received, defaults are (SIGINT, SIGTERM, SIGABRT) settable withidle
.request_kwargs (
dict
, optional) – Keyword args to control the creation of a telegram.utils.request.Request object (ignored if bot or dispatcher argument is used). The request_kwargs are very useful for the advanced users who would like to control the default timeouts and/or control the proxy used for http communication.use_context (
bool
, optional) – If set toTrue
uses the context based callback API (ignored if dispatcher argument is used). Defaults toTrue
. New users: set this toTrue
.persistence (
telegram.ext.BasePersistence
, optional) – The persistence class to store data that should be persistent over restarts (ignored if dispatcher argument is used).defaults (
telegram.ext.Defaults
, optional) – An object containing default values to be used if not set explicitly in the bot methods.arbitrary_callback_data (
bool
|int
|None
, optional) –Whether to allow arbitrary objects as callback data for
telegram.InlineKeyboardButton
. Pass an integer to specify the maximum number of cached objects. For more details, please see our wiki. Defaults toFalse
.New in version 13.6.
context_types (
telegram.ext.ContextTypes
, optional) –Pass an instance of
telegram.ext.ContextTypes
to customize the types used in thecontext
interface. If not passed, the defaults documented intelegram.ext.ContextTypes
will be used.New in version 13.6.
- Raises
ValueError – If both
token
andbot
are passed or none of them.
-
bot
¶ The bot used with this Updater.
- Type
-
user_sig_handler
¶ Optional. Function to be called when a signal is received.
- Type
function
-
update_queue
¶ Queue for the updates.
- Type
Queue
-
job_queue
¶ Jobqueue for the updater.
-
dispatcher
¶ Dispatcher that handles the updates and dispatches them to the handlers.
-
running
¶ Indicates if the updater is running.
- Type
bool
-
persistence
¶ Optional. The persistence class to store data that should be persistent over restarts.
-
use_context
¶ Optional.
True
if using context based callbacks.- Type
bool
-
idle
(stop_signals=(<Signals.SIGINT: 2>, <Signals.SIGTERM: 15>, <Signals.SIGABRT: 6>))¶ Blocks until one of the signals are received and stops the updater.
- Parameters
stop_signals (
list
|tuple
) – List containing signals from the signal module that should be subscribed to.Updater.stop()
will be called on receiving one of those signals. Defaults to (SIGINT
,SIGTERM
,SIGABRT
).
-
start_polling
(poll_interval=0.0, timeout=10, clean=None, bootstrap_retries=- 1, read_latency=2.0, allowed_updates=None, drop_pending_updates=None)¶ Starts polling updates from Telegram.
- Parameters
poll_interval (
float
, optional) – Time to wait between polling updates from Telegram in seconds. Default is0.0
.timeout (
float
, optional) – Passed totelegram.Bot.get_updates()
.drop_pending_updates (
bool
, optional) –Whether to clean any pending updates on Telegram servers before actually starting to poll. Default is
False
.New in version 13.4.
clean (
bool
, optional) –Alias for
drop_pending_updates
.Deprecated since version 13.4: Use
drop_pending_updates
instead.bootstrap_retries (
int
, optional) –Whether the bootstrapping phase of the
telegram.ext.Updater
will retry on failures on the Telegram server.< 0 - retry indefinitely (default)
0 - no retries
> 0 - retry up to X times
allowed_updates (List[
str
], optional) – Passed totelegram.Bot.get_updates()
.read_latency (
float
|int
, optional) – Grace time in seconds for receiving the reply from server. Will be added to thetimeout
value and used as the read timeout from server (Default:2
).
- Returns
The update queue that can be filled from the main thread.
- Return type
Queue
-
start_webhook
(listen='127.0.0.1', port=80, url_path='', cert=None, key=None, clean=None, bootstrap_retries=0, webhook_url=None, allowed_updates=None, force_event_loop=None, drop_pending_updates=None, ip_address=None, max_connections=40)¶ Starts a small http server to listen for updates via webhook. If
cert
andkey
are not provided, the webhook will be started directly on http://listen:port/url_path, so SSL can be handled by another application. Else, the webhook will be started on https://listen:port/url_path. Also callstelegram.Bot.set_webhook()
as required.Changed in version 13.4:
start_webhook()
now always callstelegram.Bot.set_webhook()
, so passwebhook_url
instead of callingupdater.bot.set_webhook(webhook_url)
manually.- Parameters
listen (
str
, optional) – IP-Address to listen on. Default127.0.0.1
.port (
int
, optional) – Port the bot should be listening on. Default80
.url_path (
str
, optional) – Path inside url.cert (
str
, optional) – Path to the SSL certificate file.key (
str
, optional) – Path to the SSL key file.drop_pending_updates (
bool
, optional) –Whether to clean any pending updates on Telegram servers before actually starting to poll. Default is
False
.New in version 13.4.
clean (
bool
, optional) –Alias for
drop_pending_updates
.Deprecated since version 13.4: Use
drop_pending_updates
instead.bootstrap_retries (
int
, optional) –Whether the bootstrapping phase of the
telegram.ext.Updater
will retry on failures on the Telegram server.< 0 - retry indefinitely (default)
0 - no retries
> 0 - retry up to X times
webhook_url (
str
, optional) – Explicitly specify the webhook url. Useful behind NAT, reverse proxy, etc. Default is derived fromlisten
,port
&url_path
.ip_address (
str
, optional) –Passed to
telegram.Bot.set_webhook()
.New in version 13.4.
allowed_updates (List[
str
], optional) – Passed totelegram.Bot.set_webhook()
.force_event_loop (
bool
, optional) –Legacy parameter formerly used for a workaround on Windows + Python 3.8+. No longer has any effect.
Deprecated since version 13.6: Since version 13.6,
tornade>=6.1
is required, which resolves the former issue.max_connections (
int
, optional) –Passed to
telegram.Bot.set_webhook()
.New in version 13.6.
- Returns
The update queue that can be filled from the main thread.
- Return type
Queue
-
stop
()¶ Stops the polling/webhook thread, the dispatcher and the job queue.