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)

Bases: object

This class, which employs the telegram.ext.Dispatcher, provides a frontend to telegram.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 a token argument.

  • If you supply a bot, you will need to pass defaults to both the bot and the telegram.ext.Updater.

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) – Takes signum, frame as positional arguments. This will be called when a signal is received, defaults are (SIGINT, SIGTERM, SIGABRT) settable with idle.

  • 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 to True uses the context based callback API (ignored if dispatcher argument is used). Defaults to True. New users: set this to True.

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

Raises

ValueError – If both token and bot are passed or none of them.

bot

The bot used with this Updater.

Type

telegram.Bot

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.

Type

telegram.ext.JobQueue

dispatcher

Dispatcher that handles the updates and dispatches them to the handlers.

Type

telegram.ext.Dispatcher

running

Indicates if the updater is running.

Type

bool

persistence

Optional. The persistence class to store data that should be persistent over restarts.

Type

telegram.ext.BasePersistence

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 is 0.0.

  • timeout (float, optional) – Passed to telegram.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 to telegram.Bot.get_updates().

  • read_latency (float | int, optional) – Grace time in seconds for receiving the reply from server. Will be added to the timeout 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=False, drop_pending_updates=None, ip_address=None)

Starts a small http server to listen for updates via webhook. If cert and key 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 calls telegram.Bot.set_webhook() as required.

Note

Due to an incompatibility of the Tornado library PTB uses for the webhook with Python 3.8+ on Windows machines, PTB will attempt to set the event loop to asyncio.SelectorEventLoop and raise an exception, if an incompatible event loop has already been specified. See this thread for more details. To suppress the exception, set force_event_loop to True.

Parameters
  • listen (str, optional) – IP-Address to listen on. Default 127.0.0.1.

  • port (int, optional) – Port the bot should be listening on. Default 80.

  • 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 from listen, port & url_path.

  • ip_address (str, optional) –

    Passed to telegram.Bot.set_webhook().

    New in version 13.4.

  • allowed_updates (List[str], optional) – Passed to telegram.Bot.set_webhook().

  • force_event_loop (bool, optional) – Force using the current event loop. See above note for details. Defaults to False

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.