Thetelegram package contains PTBs Python implementation of the classes and methods defined in theBot API.This implementation is manually updated whenever Telegram releases a new version of the API.Due to the nature of this open-source library, the implementation work usually takes some time, depending on how much changed.However, users of PTB might want to immediately use the new functionality provided by Telegram.PTB therefore provides mechanism that make exactly this possible, i.e. accessing information from the Bot API that has no native PTB implementation yet.Below, we will describe the mechanisms in detail.

Telegram sends data in the form of JSON objects either for updates that your bot receives or as return value of methods.When Telegram adds new attributes ("fields") to these objects that, the corresponding attributes in PTBs classes will be missing.However, any additional data that is not yet covered by the native Python attributes will be gathered in theTelegramObject.api_kwargs attribute (note thatTelegramObject is the base class of (almost) all other classes in thetelegram package).

For example, imagine that Telegram adds a new field calledread_date to theMessage class. Then accessingupdate.message.read_date is possible only after PTB was updated, however accessingupdate.message.api_kwargs["read_date"] would give the value provided by Telegram.

As another example, imagine that Telegram adds a new filed calleduser_online_status_updated to theUpdate class. Then accessingupdate.user_online_status_updated is again not immediately possible. Moreover, there is not yet a handler intelegram.ext to handle these new kinds of updates. However, in this case you can e.g. useTypeHandler to catch these updates, like this

fromtelegramimportUpdatefromtelegram.extimportTypeHandlerasyncdefcallback(update,context):ifstatus_updated:=update.api_kwargs.get("user_online_status_updated"):print(status_updated)application.add_handler(TypeHandler(Update,callback))

Of course you can also implement your own subclass ofBaseHandler that checks for the presence of the keyuser_online_status_updated inupdate.api_kwargs. See alsothis page.

The Bot API also receives objects from you, namely as input arguments for the different Bot methods. For example,Bot.set_my_command expects an array ofBotCommand objects.If Telegram adds new fields to objects that you send as input to Telegram, the corresponding arguments in PTBs classes will be missing.However, any additional data that is not yet covered by the native Python attributes can be passed via the argumentapi_kwargs ofTelegramObject (note thatTelegramObject is the base class of (almost) all other classes in thetelegram package).

For example, imagine that Telegram adds a new field calledemoji to theBotCommand class such that this emoji is shown somewhere in the chat when the command is selected by the user. Then passing the argument viaBotCommand("command", "description", emoji="💥") is possible only after PTB was updated. However, you can already do

BotCommand("command","description",api_kwargs={"emoji":"💥"})

and PTB will pass the data along to Telegram.

All bot methods have a number of parameters defined by Telegram.If Telegram adds new parameters to methods that you can specify, the corresponding arguments in PTBs the methods oftelegram.Bot (and the corresponding shortcuts) will be missing.However, any additional data that is not yet covered by the native Python arguments can be passed via the argumentapi_kwargs of the respective method.

For example, imagine that Telegram adds a new parameter calleddelete_after to thesend_message method such that the message is deleted automatically after the specified time. Then passing the argument viaawait bot.send_message(chat_id=123, text="Hello!", delete_after=42) is possible only after PTB was updated. However, you can already do

awaitbot.send_message(chat_id=123,text="Hello!",api_kwargs={"delete_after":42})

and PTB will pass the data along to Telegram.

Sometimes, Telegram adds entirely new methods to the API that you can use to trigger novel functionality.If Telegram adds such a new method, the corresponding method of PTBs classtelegram.Bot will be missing.However, PTB provides the methodBot.do_api_request that allows you to make any API call to Telegram.

For example, imagine that Telegram adds a new method calledget_message allowing your bot to fetch information about a specific method. Then calling that method viaawait bot.get_message(chat_id=123, message_id=456) is possible only after PTB was updated. However, you can already do

awaitbot.do_api_request(endpoint="get_message",api_kwargs={"message_id":456,"chat_id":123},return_type=Message)

and PTB will call the corresponding Bot API method with the given parameters and return the result as aMessage object.