Updater

class telegram.ext.Updater(bot, update_queue)[source]

Bases: typing.AsyncContextManager

This class fetches updates for the bot either via long polling or by starting a webhook server. Received updates are enqueued into the update_queue and may be fetched from there to handle them appropriately.

Instances of this class can be used as asyncio context managers, where

async with updater:
    # code

is roughly equivalent to

try:
    await updater.initialize()
    # code
finally:
    await updater.shutdown()

Use In

telegram.ext.ApplicationBuilder.updater()

Available In

telegram.ext.Application.updater

See also

__aenter__() and __aexit__().

See also

Architecture Overview, Builder Pattern

Changed in version 20.0:

  • Removed argument and attribute user_sig_handler

  • The only arguments and attributes are now bot and update_queue as now the sole purpose of this class is to fetch updates. The entry point to a PTB application is now telegram.ext.Application.

Parameters:
bot[source]

The bot used with this Updater.

Type:

telegram.Bot

update_queue[source]

Queue for the updates.

Type:

asyncio.Queue

async __aenter__()[source]

Asynchronous context manager which initializes the Updater.

Returns:

The initialized Updater instance.

Raises:

Exception – If an exception is raised during initialization, shutdown() is called in this case.

async __aexit__(exc_type, exc_val, exc_tb)[source]

Asynchronous context manager which shuts down the Updater.

__repr__()[source]

Give a string representation of the updater in the form Updater[bot=...].

As this class doesn’t implement object.__str__(), the default implementation will be used, which is equivalent to __repr__().

Returns:

str

async initialize()[source]

Initializes the Updater & the associated bot by calling telegram.Bot.initialize().

See also

shutdown()

async shutdown()[source]

Shutdown the Updater & the associated bot by calling telegram.Bot.shutdown().

See also

initialize()

Raises:

RuntimeError – If the updater is still running.

async start_polling(poll_interval=0.0, timeout=10, bootstrap_retries=-1, read_timeout=None, write_timeout=None, connect_timeout=None, pool_timeout=None, allowed_updates=None, drop_pending_updates=None, error_callback=None)[source]

Starts polling updates from Telegram.

Changed in version 20.0: Removed the clean argument in favor of drop_pending_updates.

Parameters:
Returns:

The update queue that can be filled from the main thread.

Return type:

asyncio.Queue

Raises:

RuntimeError – If the updater is already running or was not initialized.

async start_webhook(listen='127.0.0.1', port=80, url_path='', cert=None, key=None, bootstrap_retries=0, webhook_url=None, allowed_updates=None, drop_pending_updates=None, ip_address=None, max_connections=40, secret_token=None, unix=None)[source]

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.

Important

If you want to use this method, you must install PTB with the optional requirement webhooks, i.e.

pip install "python-telegram-bot[webhooks]"

See also

Webhooks

Changed in version 13.4: start_webhook() now always calls telegram.Bot.set_webhook(), so pass webhook_url instead of calling updater.bot.set_webhook(webhook_url) manually.

Changed in version 20.0:

  • Removed the clean argument in favor of drop_pending_updates and removed the deprecated argument force_event_loop.

Parameters:

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

  • port (int, optional) – Port the bot should be listening on. Must be one of telegram.constants.SUPPORTED_WEBHOOK_PORTS unless the bot is running behind a proxy. Defaults to 80.

  • url_path (str, optional) – Path inside url (http(s)://listen:port/<url_path>). Defaults to ''.

  • cert (pathlib.Path | str, optional) – Path to the SSL certificate file.

  • key (pathlib.Path | 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.

  • bootstrap_retries (int, optional) –

    Whether the bootstrapping phase of the telegram.ext.Updater will retry on failures on the Telegram server.

    • < 0 - retry indefinitely

    • 0 - no retries (default)

    • > 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, cert, and key.

  • ip_address (str, optional) –

    Passed to telegram.Bot.set_webhook(). Defaults to None.

    New in version 13.4.

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

  • max_connections (int, optional) –

    Passed to telegram.Bot.set_webhook(). Defaults to 40.

    New in version 13.6.

  • secret_token (str, optional) –

    Passed to telegram.Bot.set_webhook(). Defaults to None.

    When added, the web server started by this call will expect the token to be set in the X-Telegram-Bot-Api-Secret-Token header of an incoming request and will raise a http.HTTPStatus.FORBIDDEN error if either the header isn’t set or it is set to a wrong token.

    New in version 20.0.

  • unix (pathlib.Path | str, optional) –

    Path to the unix socket file. Path does not need to exist, in which case the file will be created.

    Caution

    This parameter is a replacement for the default TCP bind. Therefore, it is mutually exclusive with listen and port. When using this param, you must also run a reverse proxy to the unix socket and set the appropriate webhook_url.

    New in version 20.8.

Returns:

The update queue that can be filled from the main thread.

Return type:

queue.Queue

Raises:

RuntimeError – If the updater is already running or was not initialized.

async stop()[source]

Stops the polling/webhook.

See also

start_polling(), start_webhook()

Raises:

RuntimeError – If the updater is not running.