ApplicationBuilder¶

class telegram.ext.ApplicationBuilder[source]¶

This class serves as initializer for telegram.ext.Application via the so called builder pattern. To build a telegram.ext.Application, one first initializes an instance of this class. Arguments for the telegram.ext.Application to build are then added by subsequently calling the methods of the builder. Finally, the telegram.ext.Application is built by calling build(). In the simplest case this can look like the following example.

Example

application = ApplicationBuilder().token("TOKEN").build()

Please see the description of the individual methods for information on which arguments can be set and what the defaults are when not called. When no default is mentioned, the argument will not be used by default.

Note

Some arguments are mutually exclusive. E.g. after calling token(), you can’t set a custom bot with bot() and vice versa.
Unless a custom telegram.Bot instance is set via bot(), build() will use telegram.ext.ExtBot for the bot.

See also

Your First Bot, Builder Pattern

Changed in version 22.0: Removed deprecated methods proxy_url and get_updates_proxy_url.

application_class(application_class, kwargs=None)[source]¶

Sets a custom subclass instead of telegram.ext.Application. The subclass’s __init__ should look like this

def __init__(self, custom_arg_1, custom_arg_2, ..., **kwargs):
    super().__init__(**kwargs)
    self.custom_arg_1 = custom_arg_1
    self.custom_arg_2 = custom_arg_2

Parameters:

application_class (type) – A subclass of telegram.ext.Application
kwargs (dict[str, object], optional) – Keyword arguments for the initialization. Defaults to an empty dict.

Returns:

The same builder with the updated argument.

Return type:

ApplicationBuilder

arbitrary_callback_data(arbitrary_callback_data)[source]¶

Specifies whether telegram.ext.Application.bot should allow arbitrary objects as callback data for telegram.InlineKeyboardButton and how many keyboards should be cached in memory. If not called, only strings can be used as callback data and no data will be stored in memory.

Important

If you want to use this feature, you must install PTB with the optional requirement callback-data, i.e.

pip install "python-telegram-bot[callback-data]"

Examples

Arbitrary callback_data Bot

See also

Arbitrary callback_data

Parameters:: arbitrary_callback_data (bool | int) – If True is passed, the default cache size of 1024 will be used. Pass an integer to specify a different cache size.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

base_file_url(base_file_url)[source]¶

Sets the base file URL for telegram.ext.Application.bot. If not called, will default to 'https://api.telegram.org/file/bot'.

Changed in version 21.11: Supports callable input and string formatting.

Parameters:: base_file_url (str | Callable[[str], str]) – The URL or input for the URL as accepted by telegram.Bot.base_file_url.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

base_url(base_url)[source]¶

Sets the base URL for telegram.ext.Application.bot. If not called, will default to 'https://api.telegram.org/bot'.

Changed in version 21.11: Supports callable input and string formatting.

Parameters:: base_url (str | Callable[[str], str]) – The URL or input for the URL as accepted by telegram.Bot.base_url.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

bot(bot)[source]¶

Sets a telegram.Bot instance for telegram.ext.Application.bot. Instances of subclasses like telegram.ext.ExtBot are also valid.

Parameters:: bot (telegram.Bot) – The bot.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

build()[source]¶

Builds a telegram.ext.Application with the provided arguments.

Calls telegram.ext.JobQueue.set_application() and telegram.ext.BasePersistence.set_bot() if appropriate.

Returns:: telegram.ext.Application

concurrent_updates(concurrent_updates)[source]¶

Specifies if and how many updates may be processed concurrently instead of one by one. If not called, updates will be processed one by one.

Warning

Processing updates concurrently is not recommended when stateful handlers like telegram.ext.ConversationHandler are used. Only use this if you are sure that your bot does not (explicitly or implicitly) rely on updates being processed sequentially.

Tip

When making requests to the Bot API in an asynchronous fashion (e.g. via block=False, Application.create_task, concurrent_updates() or the JobQueue), it can happen that more requests are being made in parallel than there are connections in the pool. If the number of requests is much higher than the number of connections, even setting pool_timeout() to a larger value may not always be enough to prevent pool timeouts. You should therefore set concurrent_updates(), connection_pool_size() and pool_timeout() to values that make sense for your setup.

Parameters:

concurrent_updates (bool | int | BaseUpdateProcessor) –

Passing True will allow for 256 updates to be processed concurrently using telegram.ext.SimpleUpdateProcessor. Pass an integer to specify a different number of updates that may be processed concurrently. Pass an instance of telegram.ext.BaseUpdateProcessor to use that instance for handling updates concurrently.

Changed in version 20.4: Now accepts BaseUpdateProcessor instances.

Returns:

The same builder with the updated argument.

Return type:

ApplicationBuilder

connect_timeout(connect_timeout)[source]¶

Sets the connection attempt timeout for the connect_timeout parameter of telegram.Bot.request. Defaults to 5.0.

See also

get_updates_connect_timeout()

Parameters:: connect_timeout (float) – See telegram.request.HTTPXRequest.connect_timeout for more information.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

connection_pool_size(connection_pool_size)[source]¶

Sets the size of the connection pool for the connection_pool_size parameter of telegram.Bot.request. Defaults to 256.

Tip

See also

get_updates_connection_pool_size()

Parameters:: connection_pool_size (int) – The size of the connection pool.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

context_types(context_types)[source]¶

Sets a telegram.ext.ContextTypes instance for telegram.ext.Application.context_types.

Examples

Context Types Bot

Parameters:: context_types (telegram.ext.ContextTypes) – The context types.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

defaults(defaults)[source]¶

Sets the telegram.ext.Defaults instance for telegram.ext.Application.bot.

See also

Adding Defaults to Your Bot

Parameters:: defaults (telegram.ext.Defaults) – The defaults instance.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

get_updates_connect_timeout(get_updates_connect_timeout)[source]¶

Sets the connection attempt timeout for the telegram.request.HTTPXRequest.connect_timeout parameter which is used for the telegram.Bot.get_updates() request. Defaults to 5.0.

See also

connect_timeout()

Parameters:: get_updates_connect_timeout (float) – See telegram.request.HTTPXRequest.connect_timeout for more information.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

get_updates_connection_pool_size(get_updates_connection_pool_size)[source]¶

Sets the size of the connection pool for the telegram.request.HTTPXRequest.connection_pool_size parameter which is used for the telegram.Bot.get_updates() request. Defaults to 1.

See also

connection_pool_size()

Parameters:: get_updates_connection_pool_size (int) – The size of the connection pool.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

get_updates_http_version(get_updates_http_version)[source]¶

Sets the HTTP protocol version which is used for the http_version parameter which is used in the telegram.Bot.get_updates() request. By default, HTTP/1.1 is used.

See also

http_version()

Note

Users have observed stability issues with HTTP/2, which happen due to how the h2 library handles cancellations of keepalive connections. See #3556 for a discussion.

You will also need to install the http2 dependency. Keep in mind that the HTTP/1.1 implementation may be considered the “more robust option at this time”.

pip install httpx[http2]

Added in version 20.1.

Changed in version 20.2: Reset the default version to 1.1.

Parameters:

get_updates_http_version (str) –

Pass "2" or "2.0" if you’d like to use HTTP/2 for making requests to Telegram. Defaults to "1.1", in which case HTTP/1.1 is used.

Changed in version 20.5: Accept "2" as a valid value.

Returns:

The same builder with the updated argument.

Return type:

ApplicationBuilder

get_updates_pool_timeout(get_updates_pool_timeout)[source]¶

Sets the connection pool’s connection freeing timeout for the pool_timeout parameter which is used for the telegram.Bot.get_updates() request. Defaults to 1.0.

See also

pool_timeout()

Parameters:: get_updates_pool_timeout (float) – See telegram.request.HTTPXRequest.pool_timeout for more information.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

get_updates_proxy(get_updates_proxy)[source]¶

Sets the proxy for the telegram.request.HTTPXRequest.proxy parameter which is used for telegram.Bot.get_updates(). Defaults to None.

See also

proxy()

Added in version 20.7.

Parameters:: proxy (str | httpx.Proxy | httpx.URL) – The URL to a proxy server, a httpx.Proxy object or a httpx.URL object. See telegram.request.HTTPXRequest.proxy for more information.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

get_updates_read_timeout(get_updates_read_timeout)[source]¶

Sets the waiting timeout for the telegram.request.HTTPXRequest.read_timeout parameter which is used for the telegram.Bot.get_updates() request. Defaults to 5.0.

See also

read_timeout()

Parameters:: get_updates_read_timeout (float) – See telegram.request.HTTPXRequest.read_timeout for more information.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

get_updates_request(get_updates_request)[source]¶

Sets a telegram.request.BaseRequest instance for the get_updates_request parameter of telegram.ext.Application.bot.

See also

request()

Parameters:: get_updates_request (telegram.request.BaseRequest) – The request instance.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

get_updates_socket_options(get_updates_socket_options)[source]¶

Sets the options for the socket_options parameter of telegram.Bot.get_updates_request. Defaults to None.

See also

socket_options()

Added in version 20.7.

Parameters:: get_updates_socket_options (Collection[tuple], optional) – Socket options. See telegram.request.HTTPXRequest.socket_options for more information.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

get_updates_write_timeout(get_updates_write_timeout)[source]¶

Sets the write operation timeout for the telegram.request.HTTPXRequest.write_timeout parameter which is used for the telegram.Bot.get_updates() request. Defaults to 5.0.

See also

write_timeout()

Parameters:: get_updates_write_timeout (float) – See telegram.request.HTTPXRequest.write_timeout for more information.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

http_version(http_version)[source]¶

Sets the HTTP protocol version which is used for the http_version parameter of telegram.Bot.request. By default, HTTP/1.1 is used.

See also

get_updates_http_version()

Note

Users have observed stability issues with HTTP/2, which happen due to how the h2 library handles cancellations of keepalive connections. See #3556 for a discussion.

If you want to use HTTP/2, you must install PTB with the optional requirement http2, i.e.

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

Keep in mind that the HTTP/1.1 implementation may be considered the “more robust option at this time”.

Added in version 20.1.

Changed in version 20.2: Reset the default version to 1.1.

Parameters:

http_version (str) –

Pass "2" or "2.0" if you’d like to use HTTP/2 for making requests to Telegram. Defaults to "1.1", in which case HTTP/1.1 is used.

Changed in version 20.5: Accept "2" as a valid value.

Returns:

The same builder with the updated argument.

Return type:

ApplicationBuilder

job_queue(job_queue)[source]¶

Sets a telegram.ext.JobQueue instance for telegram.ext.Application.job_queue. If not called, a job queue will be instantiated if the requirements of telegram.ext.JobQueue are installed.

Examples

Timer Bot

See also

Job Queue

Note

telegram.ext.JobQueue.set_application() will be called automatically by build().
The job queue will be automatically started and stopped by telegram.ext.Application.start() and telegram.ext.Application.stop(), respectively.
When passing None or when the requirements of telegram.ext.JobQueue are not installed, telegram.ext.ConversationHandler.conversation_timeout can not be used, as this uses telegram.ext.Application.job_queue internally.

Parameters:: job_queue (telegram.ext.JobQueue) – The job queue. Pass None if you don’t want to use a job queue.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

local_mode(local_mode)[source]¶

Specifies the value for local_mode for the telegram.ext.Application.bot. If not called, will default to False.

See also

Local Bot API Server

Parameters:: local_mode (bool) – Whether the bot should run in local mode.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

media_write_timeout(media_write_timeout)[source]¶

Sets the media write operation timeout for the media_write_timeout parameter of telegram.Bot.request. Defaults to 20.

Added in version 21.0.

Parameters:: media_write_timeout (float) – See telegram.request.HTTPXRequest.media_write_timeout for more information.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

persistence(persistence)[source]¶

Sets a telegram.ext.BasePersistence instance for telegram.ext.Application.persistence.

Note

When using a persistence, note that all data stored in context.user_data, context.chat_data, context.bot_data and in telegram.ext.ExtBot.callback_data_cache must be copyable with copy.deepcopy(). This is due to the data being deep copied before handing it over to the persistence in order to avoid race conditions.

Examples

Persistent Conversation Bot

See also

Making Your Bot Persistent

Warning

If a telegram.ext.ContextTypes instance is set via context_types(), the persistence instance must use the same types!

Parameters:: persistence (telegram.ext.BasePersistence) – The persistence instance.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

pool_timeout(pool_timeout)[source]¶

Sets the connection pool’s connection freeing timeout for the pool_timeout parameter of telegram.Bot.request. Defaults to 1.0.

Tip

See also

get_updates_pool_timeout()

Parameters:: pool_timeout (float) – See telegram.request.HTTPXRequest.pool_timeout for more information.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

post_init(post_init)[source]¶

Sets a callback to be executed by Application.run_polling() and Application.run_webhook() after executing Application.initialize() but before executing Updater.start_polling() or Updater.start_webhook(), respectively.

Tip

This can be used for custom startup logic that requires to await coroutines, e.g. setting up the bots commands via set_my_commands().

Example

async def post_init(application: Application) -> None:
    await application.bot.set_my_commands([('start', 'Starts the bot')])

application = Application.builder().token("TOKEN").post_init(post_init).build()

Note

If you implement custom logic that implies that you will not be using Application’s methods run_polling() or run_webhook() to run your application (like it’s done in Custom Webhook Bot Example), the callback you set in this method will not be called automatically. So instead of setting a callback with this method, you have to explicitly await the function that you want to run at this stage of your application’s life (in the example mentioned above, that would be in async with application context manager).

See also

post_stop(), post_shutdown()

Parameters:

post_init (coroutine function) –

The custom callback. Must be a coroutine function and must accept exactly one positional argument, which is the Application:

async def post_init(application: Application) -> None:

Returns:

The same builder with the updated argument.

Return type:

ApplicationBuilder

post_shutdown(post_shutdown)[source]¶

Sets a callback to be executed by Application.run_polling() and Application.run_webhook() after executing Updater.shutdown() and Application.shutdown().

Tip

This can be used for custom shutdown logic that requires to await coroutines, e.g. closing a database connection

Example

async def post_shutdown(application: Application) -> None:
    await application.bot_data['database'].close()

application = Application.builder()
                        .token("TOKEN")
                        .post_shutdown(post_shutdown)
                        .build()

Note

See also

post_init(), post_stop()

Parameters:

post_shutdown (coroutine function) –

The custom callback. Must be a coroutine function and must accept exactly one positional argument, which is the Application:

async def post_shutdown(application: Application) -> None:

Returns:

The same builder with the updated argument.

Return type:

ApplicationBuilder

post_stop(post_stop)[source]¶

Sets a callback to be executed by Application.run_polling() and Application.run_webhook() after executing Updater.stop() and Application.stop().

Added in version 20.1.

Tip

This can be used for custom stop logic that requires to await coroutines, e.g. sending message to a chat before shutting down the bot.

Hint

The callback will be called only, if Application.stop() was indeed called successfully. For example, if the application is stopped early by calling Application.stop_running() within post_init(), then the set callback will not be called.

Example

async def post_stop(application: Application) -> None:
    await application.bot.send_message(123456, "Shutting down...")

application = Application.builder()
                        .token("TOKEN")
                        .post_stop(post_stop)
                        .build()

Note

See also

post_init(), post_shutdown()

Parameters:

post_stop (coroutine function) –

The custom callback. Must be a coroutine function and must accept exactly one positional argument, which is the Application:

async def post_stop(application: Application) -> None:

Returns:

The same builder with the updated argument.

Return type:

ApplicationBuilder

private_key(private_key, password=None)[source]¶

Sets the private key and corresponding password for decryption of telegram passport data for telegram.ext.Application.bot.

Examples

Passport Bot

See also

Telegram Passports

Parameters:

private_key (bytes | str | pathlib.Path) – The private key or the file path of a file that contains the key. In the latter case, the file’s content will be read automatically.
password (bytes | str | pathlib.Path, optional) – The corresponding password or the file path of a file that contains the password. In the latter case, the file’s content will be read automatically.

Returns:

The same builder with the updated argument.

Return type:

ApplicationBuilder

proxy(proxy)[source]¶

Sets the proxy for the proxy parameter of telegram.Bot.request. Defaults to None.

See also

get_updates_proxy()

Added in version 20.7.

Parameters:: proxy (str | httpx.Proxy | httpx.URL) – The URL to a proxy server, a httpx.Proxy object or a httpx.URL object. See telegram.request.HTTPXRequest.proxy for more information.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

rate_limiter(rate_limiter)[source]¶

Sets a telegram.ext.BaseRateLimiter instance for the telegram.ext.ExtBot.rate_limiter parameter of telegram.ext.Application.bot.

Parameters:: rate_limiter (telegram.ext.BaseRateLimiter) – The rate limiter.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

read_timeout(read_timeout)[source]¶

Sets the waiting timeout for the read_timeout parameter of telegram.Bot.request. Defaults to 5.0.

See also

get_updates_read_timeout()

Parameters:: read_timeout (float) – See telegram.request.HTTPXRequest.read_timeout for more information.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

request(request)[source]¶

Sets a telegram.request.BaseRequest instance for the telegram.Bot.request parameter of telegram.ext.Application.bot.

See also

get_updates_request()

Parameters:: request (telegram.request.BaseRequest) – The request instance.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

socket_options(socket_options)[source]¶

Sets the options for the socket_options parameter of telegram.Bot.request. Defaults to None.

See also

get_updates_socket_options()

Added in version 20.7.

Parameters:: socket_options (Collection[tuple], optional) – Socket options. See telegram.request.HTTPXRequest.socket_options for more information.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

token(token)[source]¶

Sets the token for telegram.ext.Application.bot.

Parameters:: token (str) – The token.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

update_queue(update_queue)[source]¶

Sets a asyncio.Queue instance for telegram.ext.Application.update_queue, i.e. the queue that the application will fetch updates from. Will also be used for the telegram.ext.Application.updater. If not called, a queue will be instantiated.

See also

telegram.ext.Updater.update_queue

Parameters:: update_queue (asyncio.Queue) – The queue.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

updater(updater)[source]¶

Sets a telegram.ext.Updater instance for telegram.ext.Application.updater. The telegram.ext.Updater.bot and telegram.ext.Updater.update_queue will be used for telegram.ext.Application.bot and telegram.ext.Application.update_queue, respectively.

Parameters:: updater (telegram.ext.Updater | None) – The updater instance or None if no updater should be used.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder

write_timeout(write_timeout)[source]¶

Sets the write operation timeout for the write_timeout parameter of telegram.Bot.request. Defaults to 5.0.

See also

get_updates_write_timeout()

Parameters:: write_timeout (float) – See telegram.request.HTTPXRequest.write_timeout for more information.
Returns:: The same builder with the updated argument.
Return type:: ApplicationBuilder