ApplicationBuilder¶

classtelegram.ext.ApplicationBuilder[source]¶

This class serves as initializer fortelegram.ext.Application via the so calledbuilder pattern. To build atelegram.ext.Application, one first initializes aninstance of this class. Arguments for thetelegram.ext.Application to build are thenadded by subsequently calling the methods of the builder. Finally, thetelegram.ext.Application is built by callingbuild(). In the simplest case thiscan 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 beset and what the defaults are when not called. When no default is mentioned, the argument willnot be used by default.

Note

• Some arguments are mutually exclusive. E.g. after callingtoken(), you can’t seta custom bot withbot() and vice versa.

• Unless a customtelegram.Bot instance is set viabot(),build() willusetelegram.ext.ExtBot for the bot.

See also

Your First Bot,Builder Pattern

Changed in version 22.0:Removed deprecated methodsproxy_url andget_updates_proxy_url.

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

Sets a custom subclass instead oftelegram.ext.Application. Thesubclass’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_1self.custom_arg_2=custom_arg_2

Parameters:

• application_class (type) – A subclass oftelegram.ext.Application

• kwargs (dict[str,object], optional) – Keyword arguments for theinitialization. Defaults to an empty dict.

Returns:

The same builder with the updated argument.

Return type:

ApplicationBuilder

arbitrary_callback_data(arbitrary_callback_data)[source]¶

Specifies whethertelegram.ext.Application.bot should allow arbitrary objects ascallback data fortelegram.InlineKeyboardButton and how many keyboards should becached in memory. If not called, only strings can be used as callback data and no data willbe stored in memory.

Important

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

pipinstall"python-telegram-bot[callback-data]"

Examples

Arbitrary callback_data Bot

See also

Arbitrary callback_data

Parameters:

arbitrary_callback_data (bool |int) – IfTrue is passed, thedefault cache size of1024 will be used. Pass an integer to specify a differentcache size.

Returns:

The same builder with the updated argument.

Return type:

ApplicationBuilder

base_file_url(base_file_url)[source]¶

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

See also

telegram.Bot.base_file_url,Local Bot API Server,base_url()

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

Parameters:

base_file_url (str | Callable[[str],str]) – The URL orinput for the URL as accepted bytelegram.Bot.base_file_url.

Returns:

The same builder with the updated argument.

Return type:

ApplicationBuilder

base_url(base_url)[source]¶

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

See also

telegram.Bot.base_url,Local Bot API Server,base_file_url()

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

Parameters:

base_url (str | Callable[[str],str]) – The URL orinput for the URL as accepted bytelegram.Bot.base_url.

Returns:

The same builder with the updated argument.

Return type:

ApplicationBuilder

bot(bot)[source]¶

Sets atelegram.Bot instance fortelegram.ext.Application.bot. Instances of subclasses liketelegram.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 atelegram.ext.Application with the provided arguments.

Callstelegram.ext.JobQueue.set_application() andtelegram.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 liketelegram.ext.ConversationHandler are used. Only use this if you are surethat your bot does not (explicitly or implicitly) rely on updates being processedsequentially.

Tip

When making requests to the Bot API in an asynchronous fashion (e.g. viablock=False,Application.create_task,concurrent_updates() or theJobQueue), it can happen that more requestsare 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 settingpool_timeout() to a larger value may not always be enough to prevent pooltimeouts.You should therefore setconcurrent_updates(),connection_pool_size() andpool_timeout() to values that make sense for your setup.

See also

telegram.ext.Application.concurrent_updates

Parameters:

concurrent_updates (bool |int |BaseUpdateProcessor) –

PassingTrue will allow for256 updates to be processed concurrently usingtelegram.ext.SimpleUpdateProcessor. Pass an integer to specify a differentnumber of updates that may be processed concurrently. Pass an instance oftelegram.ext.BaseUpdateProcessor to use that instance for handling updatesconcurrently.

Changed in version 20.4:Now acceptsBaseUpdateProcessor instances.

Returns:

The same builder with the updated argument.

Return type:

ApplicationBuilder

connect_timeout(connect_timeout)[source]¶

Sets the connection attempt timeout for theconnect_timeout parameter oftelegram.Bot.request. Defaults to5.0.

See also

get_updates_connect_timeout()

Parameters:

connect_timeout (float) – Seetelegram.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 theconnection_pool_size parameter oftelegram.Bot.request. Defaults to256.

Tip

When making requests to the Bot API in an asynchronous fashion (e.g. viablock=False,Application.create_task,concurrent_updates() or theJobQueue), it can happen that more requestsare 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 settingpool_timeout() to a larger value may not always be enough to prevent pooltimeouts.You should therefore setconcurrent_updates(),connection_pool_size() andpool_timeout() to values that make sense for your setup.

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 atelegram.ext.ContextTypes instance fortelegram.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 thetelegram.ext.Defaults instance fortelegram.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 thetelegram.request.HTTPXRequest.connect_timeout parameter which is used forthetelegram.Bot.get_updates() request. Defaults to5.0.

See also

connect_timeout()

Parameters:

get_updates_connect_timeout (float) – Seetelegram.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 thetelegram.request.HTTPXRequest.connection_pool_size parameter which is usedfor thetelegram.Bot.get_updates() request. Defaults to1.

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 thehttp_version parameter which is used in thetelegram.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 theh2library handles cancellations ofkeepalive connections. See#3556 for a discussion.

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

pipinstallhttpx[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 useHTTP/2 for making requests to Telegram. Defaults to"1.1", in which caseHTTP/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 thepool_timeout parameter which is used for thetelegram.Bot.get_updates() request. Defaults to1.0.

See also

pool_timeout()

Parameters:

get_updates_pool_timeout (float) – Seetelegram.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 thetelegram.request.HTTPXRequest.proxyparameter which is used fortelegram.Bot.get_updates(). Defaults toNone.

See also

proxy()

Added in version 20.7.

Parameters:

proxy (str |httpx.Proxy |httpx.URL) – The URL to a proxy server,ahttpx.Proxy object or ahttpx.URL object. Seetelegram.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 thetelegram.request.HTTPXRequest.read_timeout parameter which is used for thetelegram.Bot.get_updates() request. Defaults to5.0.

See also

read_timeout()

Parameters:

get_updates_read_timeout (float) – Seetelegram.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 atelegram.request.BaseRequest instance for theget_updates_request parameter oftelegram.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 thesocket_optionsparameter oftelegram.Bot.get_updates_request. Defaults toNone.

See also

socket_options()

Added in version 20.7.

Parameters:

get_updates_socket_options (Collection[tuple], optional) – Socket options. Seetelegram.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 thetelegram.request.HTTPXRequest.write_timeout parameter which is used forthetelegram.Bot.get_updates() request. Defaults to5.0.

See also

write_timeout()

Parameters:

get_updates_write_timeout (float) – Seetelegram.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 thehttp_version parameter oftelegram.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 theh2library handles cancellations ofkeepalive connections. See#3556 for a discussion.

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

pipinstall"python-telegram-bot[http2]"

Keep in mind that the HTTP/1.1 implementation may be considered the“morerobust 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 formaking 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 atelegram.ext.JobQueue instance fortelegram.ext.Application.job_queue. If not called, a job queue will beinstantiated if the requirements oftelegram.ext.JobQueue are installed.

Examples

Timer Bot

See also

Job Queue

Note

• telegram.ext.JobQueue.set_application() will be called automatically bybuild().

• The job queue will be automatically started and stopped bytelegram.ext.Application.start() andtelegram.ext.Application.stop(),respectively.

• When passingNone or when the requirements oftelegram.ext.JobQueueare not installed,telegram.ext.ConversationHandler.conversation_timeoutcan not be used, as this usestelegram.ext.Application.job_queue internally.

Parameters:

job_queue (telegram.ext.JobQueue) – The job queue. PassNone if youdon’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 forlocal_mode for thetelegram.ext.Application.bot.If not called, will default toFalse.

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 themedia_write_timeout parameter oftelegram.Bot.request. Defaults to20.

Added in version 21.0.

Parameters:

media_write_timeout (float) – Seetelegram.request.HTTPXRequest.media_write_timeout for more information.

Returns:

The same builder with the updated argument.

Return type:

ApplicationBuilder

persistence(persistence)[source]¶

Sets atelegram.ext.BasePersistence instance fortelegram.ext.Application.persistence.

Note

When using a persistence, note that alldata stored incontext.user_data,context.chat_data,context.bot_data andintelegram.ext.ExtBot.callback_data_cache must be copyable withcopy.deepcopy(). This is due to the data being deep copied before handing it overto the persistence in order to avoid race conditions.

Examples

Persistent Conversation Bot

See also

Making Your Bot Persistent

Warning

If atelegram.ext.ContextTypes instance is set viacontext_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 thepool_timeout parameter oftelegram.Bot.request. Defaults to1.0.

Tip

When making requests to the Bot API in an asynchronous fashion (e.g. viablock=False,Application.create_task,concurrent_updates() or theJobQueue), it can happen that more requestsare 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 settingpool_timeout() to a larger value may not always be enough to prevent pooltimeouts.You should therefore setconcurrent_updates(),connection_pool_size() andpool_timeout() to values that make sense for your setup.

See also

get_updates_pool_timeout()

Parameters:

pool_timeout (float) – Seetelegram.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 byApplication.run_polling() andApplication.run_webhook()after executingApplication.initialize() butbefore executingUpdater.start_polling() orUpdater.start_webhook(),respectively.

Tip

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

Example

asyncdefpost_init(application:Application)->None:awaitapplication.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 willnot be usingApplication’s methodsrun_polling() orrun_webhook() to run your application (like it’s done inCustom Webhook Bot Example), the callback you set in this methodwill not be called automatically. So instead of setting a callback with this method, you have to explicitlyawait the function that you want to run at this stage of your application’s life (in theexample mentioned above, that would be inasyncwithapplication context manager).

See also

post_stop(),post_shutdown()

Parameters:

post_init (coroutine function) –

The custom callback. Must be acoroutine function and must accept exactly one positional argument, whichis theApplication:

asyncdefpost_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 byApplication.run_polling() andApplication.run_webhook()after executingUpdater.shutdown()andApplication.shutdown().

Tip

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

Example

asyncdefpost_shutdown(application:Application)->None:awaitapplication.bot_data['database'].close()application=Application.builder().token("TOKEN").post_shutdown(post_shutdown).build()

Note

If you implement custom logic that implies that you willnot be usingApplication’s methodsrun_polling() orrun_webhook() to run your application (like it’s done inCustom Webhook Bot Example), the callback you set in this methodwill not be called automatically. So instead of setting a callback with this method, you have to explicitlyawait the function that you want to run at this stage of your application’s life (in theexample mentioned above, that would be inasyncwithapplication context manager).

See also

post_init(),post_stop()

Parameters:

post_shutdown (coroutine function) –

The custom callback. Must be acoroutine function and must accept exactly one positional argument, whichis theApplication:

asyncdefpost_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 byApplication.run_polling() andApplication.run_webhook()after executingUpdater.stop()andApplication.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, ifApplication.stop() was indeed calledsuccessfully. For example, if the application is stopped early by callingApplication.stop_running() withinpost_init(), then the set callback willnot be called.

Example

asyncdefpost_stop(application:Application)->None:awaitapplication.bot.send_message(123456,"Shutting down...")application=Application.builder().token("TOKEN").post_stop(post_stop).build()

Note

If you implement custom logic that implies that you willnot be usingApplication’s methodsrun_polling() orrun_webhook() to run your application (like it’s done inCustom Webhook Bot Example), the callback you set in this methodwill not be called automatically. So instead of setting a callback with this method, you have to explicitlyawait the function that you want to run at this stage of your application’s life (in theexample mentioned above, that would be inasyncwithapplication context manager).

See also

post_init(),post_shutdown()

Parameters:

post_stop (coroutine function) –

The custom callback. Must be acoroutine function and must accept exactly one positional argument, whichis theApplication:

asyncdefpost_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 datafortelegram.ext.Application.bot.

Examples

Passport Bot

See also

Telegram Passports

Parameters:

• private_key (bytes |str |pathlib.Path) – The private key or thefile path of a file that contains the key. In the latter case, the file’s contentwill be read automatically.

• password (bytes |str |pathlib.Path, optional) – The correspondingpassword 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 theproxyparameter oftelegram.Bot.request. Defaults toNone.

See also

get_updates_proxy()

Added in version 20.7.

Parameters:

proxy (str |httpx.Proxy |httpx.URL) – The URL to a proxyserver, ahttpx.Proxy object or ahttpx.URL object. Seetelegram.request.HTTPXRequest.proxy for more information.

Returns:

The same builder with the updated argument.

Return type:

ApplicationBuilder

rate_limiter(rate_limiter)[source]¶

Sets atelegram.ext.BaseRateLimiter instance for thetelegram.ext.ExtBot.rate_limiter parameter oftelegram.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 theread_timeout parameter oftelegram.Bot.request. Defaults to5.0.

See also

get_updates_read_timeout()

Parameters:

read_timeout (float) – Seetelegram.request.HTTPXRequest.read_timeout for more information.

Returns:

The same builder with the updated argument.

Return type:

ApplicationBuilder

request(request)[source]¶

Sets atelegram.request.BaseRequest instance for thetelegram.Bot.request parameter oftelegram.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 thesocket_optionsparameter oftelegram.Bot.request. Defaults toNone.

See also

get_updates_socket_options()

Added in version 20.7.

Parameters:

socket_options (Collection[tuple], optional) – Socket options. Seetelegram.request.HTTPXRequest.socket_options for more information.

Returns:

The same builder with the updated argument.

Return type:

ApplicationBuilder

token(token)[source]¶

Sets the token fortelegram.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 aasyncio.Queue instance fortelegram.ext.Application.update_queue, i.e. the queue that the application willfetch updates from. Will also be used for thetelegram.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 atelegram.ext.Updater instance fortelegram.ext.Application.updater. Thetelegram.ext.Updater.bot andtelegram.ext.Updater.update_queue will be used fortelegram.ext.Application.bot andtelegram.ext.Application.update_queue,respectively.

Parameters:

updater (telegram.ext.Updater |None) – The updater instance orNone 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 thewrite_timeout parameter oftelegram.Bot.request. Defaults to5.0.

See also

get_updates_write_timeout()

Parameters:

write_timeout (float) – Seetelegram.request.HTTPXRequest.write_timeout for more information.

Returns:

The same builder with the updated argument.

Return type:

ApplicationBuilder