telegram.ext.Updater

class telegram.ext.Updater(bot, update_queue)

Bases: AbstractAsyncContextManager

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()

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 (telegram.Bot) – The bot used with this Updater.

• update_queue (asyncio.Queue) – Queue for the updates.

bot

The bot used with this Updater.

Type

telegram.Bot

update_queue

Queue for the updates.

Type

asyncio.Queue

async initialize()

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

See also

shutdown()

async shutdown()

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=2, write_timeout=None, connect_timeout=None, pool_timeout=None, allowed_updates=None, drop_pending_updates=None, error_callback=None)

Starts polling updates from Telegram.

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

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.timeout. Defaults to 10 seconds.

• 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

• read_timeout (float, optional) – Value to pass to telegram.Bot.get_updates.read_timeout. Defaults to 2.

• write_timeout (float | None, optional) – Value to pass to telegram.Bot.get_updates.write_timeout. Defaults to DEFAULT_NONE.

• connect_timeout (float | None, optional) – Value to pass to telegram.Bot.get_updates.connect_timeout. Defaults to DEFAULT_NONE.

• pool_timeout (float | None, optional) – Value to pass to telegram.Bot.get_updates.pool_timeout. Defaults to DEFAULT_NONE.

• allowed_updates (List[str], 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.

• error_callback (Callable[[telegram.error.TelegramError], None], optional) –

  Callback to handle telegram.error.TelegramError s that occur while calling telegram.Bot.get_updates() during polling. Defaults to None, in which case errors will be logged. Callback signature:

  def callback(error: telegram.error.TelegramError)
  

  Note

  The error_callback must not be a coroutine function! If asynchronous behavior of the callback is wanted, please schedule a task from within the callback.

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)

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.

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. 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. .. versionadded :: 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. .. versionadded :: 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. .. versionadded:: 13.6

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()

Stops the polling/webhook.

See also

start_polling(), start_webhook()

Raises

RuntimeError – If the updater is not running.