telegram.ext.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

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

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

Parameters

base_file_url (str) – The 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'.

Parameters

base_url (str) – The 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.

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) – Passing True will allow for 256 updates to be processed concurrently. Pass an integer to specify a different number of updates that may be processed concurrently.

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.

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

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

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.

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

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.

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.

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_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 None.

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_url(get_updates_proxy_url)[source]

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

Parameters

get_updates_proxy_url (str) – The URL to the proxy server. See telegram.request.HTTPXRequest.proxy_url 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.

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

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

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.

See also

JobQueue, timerbot.py

Note

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.

Parameters

local_mode (bool) – Whether the bot should run in local mode.

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.

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

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

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

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.

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_url(proxy_url)[source]

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

Parameters

proxy_url (str) – The URL to the proxy server. See telegram.request.HTTPXRequest.proxy_url 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.

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.

Parameters

request (telegram.request.BaseRequest) – The request instance.

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.

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.

Parameters

write_timeout (float) – See telegram.request.HTTPXRequest.write_timeout for more information.

Returns

The same builder with the updated argument.

Return type

ApplicationBuilder