Api 7.3 docs (#4246)

Co-authored-by: Abdelrahman Elkheir <90580077+aelkheir@users.noreply.github.com>

telegram/_birthdate.py

@@ -26,7 +26,7 @@
 
 class Birthdate(TelegramObject):
     """
-    This object represents a user's birthday.
+    This object describes the birthdate of a user.
 
     Objects of this class are comparable in terms of equality. Two objects of this class are
     considered equal, if their :attr:`day`, and :attr:`month` are equal.

telegram/_bot.py

@@ -2287,9 +2287,10 @@ async def send_voice(
         """
         Use this method to send audio files, if you want Telegram clients to display the file
         as a playable voice message. For this to work, your audio must be in an ``.ogg`` file
-        encoded with OPUS (other formats may be sent as Audio or Document). Bots can currently
-        send voice messages of up to :tg-const:`telegram.constants.FileSizeLimit.FILESIZE_UPLOAD`
-        in size, this limit may be changed in the future.
+        encoded with OPUS , or in .MP3 format, or in .M4A format (other formats may be sent as
+        :class:`~telegram.Audio` or :class:`~telegram.Document`). Bots can currently send voice
+        messages of up to :tg-const:`telegram.constants.FileSizeLimit.FILESIZE_UPLOAD` in size,
+        this limit may be changed in the future.
 
         Note:
             To use this method, the file must have the type :mimetype:`audio/ogg` and be no more
@@ -2610,7 +2611,9 @@ async def send_location(
             live_period (:obj:`int`, optional): Period in seconds for which the location will be
                 updated, should be between
                 :tg-const:`telegram.constants.LocationLimit.MIN_LIVE_PERIOD` and
-                :tg-const:`telegram.constants.LocationLimit.MAX_LIVE_PERIOD`.
+                :tg-const:`telegram.constants.LocationLimit.MAX_LIVE_PERIOD`, or
+                :tg-const:`telegram.constants.LocationLimit.LIVE_PERIOD_FOREVER` for live
+                locations that can be edited indefinitely.
             heading (:obj:`int`, optional): For live locations, a direction in which the user is
                 moving, in degrees. Must be between
                 :tg-const:`telegram.constants.LocationLimit.MIN_HEADING` and
@@ -2763,8 +2766,8 @@ async def edit_message_live_location(
                 can be updated, starting from the message send date. If
                 :tg-const:`telegram.constants.LocationLimit.LIVE_PERIOD_FOREVER` is specified,
                 then the location can be updated forever. Otherwise, the new value must not exceed
-                the current live_period by more than a day, and the live location expiration date
-                must remain within the next 90 days. If not specified, then `live_period`
+                the current ``live_period`` by more than a day, and the live location expiration
+                date must remain within the next 90 days. If not specified, then ``live_period``
                 remains unchanged
 
                 .. versionadded:: NEXT.VERSION.
@@ -5325,7 +5328,8 @@ async def promote_chat_member(
 
                 .. versionadded:: 20.6
             can_edit_stories (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
-                edit stories posted by other users.
+                edit stories posted by other users, post stories to the chat page, pin chat
+                stories, and access the chat's story archive
 
                 .. versionadded:: 20.6
             can_delete_stories (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can

telegram/_business.py

@@ -189,7 +189,7 @@ def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["BusinessMess
 
 class BusinessIntro(TelegramObject):
     """
-    This object represents the intro of a business account.
+    This object contains information about the start page settings of a Telegram Business account.
 
     Objects of this class are comparable in terms of equality.
     Two objects of this class are considered equal, if their
@@ -246,7 +246,7 @@ def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["BusinessIntr
 
 class BusinessLocation(TelegramObject):
     """
-    This object represents the location of a business account.
+    This object contains information about the location of a Telegram Business account.
 
     Objects of this class are comparable in terms of equality.
     Two objects of this class are considered equal, if their
@@ -298,7 +298,7 @@ def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["BusinessLoca
 
 class BusinessOpeningHoursInterval(TelegramObject):
     """
-    This object represents the time intervals describing business opening hours.
+    This object describes an interval of time during which a business is open.
 
     Objects of this class are comparable in terms of equality.
     Two objects of this class are considered equal, if their
@@ -390,7 +390,7 @@ def closing_time(self) -> Tuple[int, int, int]:
 
 class BusinessOpeningHours(TelegramObject):
     """
-    This object represents the opening hours of a business account.
+    This object describes the opening hours of a business.
 
     Objects of this class are comparable in terms of equality.
     Two objects of this class are considered equal, if their

telegram/_chatadministratorrights.py

@@ -80,8 +80,9 @@ class ChatAdministratorRights(TelegramObject):
             .. versionadded:: 20.6
             .. versionchanged:: 21.0
                 |non_optional_story_argument|
-        can_edit_stories (:obj:`bool`): :obj:`True`, if the administrator can edit
-            stories posted by other users.
+        can_edit_stories (:obj:`bool`): :obj:`True`, if the administrator can edit stories posted
+            by other users, post stories to the chat page, pin chat stories, and access the chat's
+            story archive
 
             .. versionadded:: 20.6
             .. versionchanged:: 21.0
@@ -128,8 +129,9 @@ class ChatAdministratorRights(TelegramObject):
             .. versionadded:: 20.6
             .. versionchanged:: 21.0
                 |non_optional_story_argument|
-        can_edit_stories (:obj:`bool`): :obj:`True`, if the administrator can edit
-            stories posted by other users.
+        can_edit_stories (:obj:`bool`): :obj:`True`, if the administrator can edit stories posted
+            by other users, post stories to the chat page, pin chat stories, and access the chat's
+            story archive
 
             .. versionadded:: 20.6
             .. versionchanged:: 21.0

telegram/_chatmember.py

@@ -235,8 +235,9 @@ class ChatMemberAdministrator(ChatMember):
             .. versionadded:: 20.6
             .. versionchanged:: 21.0
                 |non_optional_story_argument|
-        can_edit_stories (:obj:`bool`): :obj:`True`, if the administrator can edit
-            stories posted by other users.
+        can_edit_stories (:obj:`bool`): :obj:`True`, if the administrator can edit stories posted
+            by other users, post stories to the chat page, pin chat stories, and access the chat's
+            story archive
 
             .. versionadded:: 20.6
             .. versionchanged:: 21.0
@@ -294,8 +295,9 @@ class ChatMemberAdministrator(ChatMember):
             .. versionadded:: 20.6
             .. versionchanged:: 21.0
                 |non_optional_story_argument|
-        can_edit_stories (:obj:`bool`): :obj:`True`, if the administrator can edit
-            stories posted by other users.
+        can_edit_stories (:obj:`bool`): :obj:`True`, if the administrator can edit stories posted
+            by other users, post stories to the chat page, pin chat stories, and access the chat's
+            story archive
 
             .. versionadded:: 20.6
             .. versionchanged:: 21.0

telegram/_forcereply.py

@@ -30,7 +30,8 @@ class ForceReply(TelegramObject):
     Upon receiving a message with this object, Telegram clients will display a reply interface to
     the user (act as if the user has selected the bot's message and tapped 'Reply'). This can be
     extremely useful if you want to create user-friendly step-by-step interfaces without having
-    to sacrifice privacy mode.
+    to sacrifice `privacy mode <https://core.telegram.org/bots/features#privacy-mode>`_. Not
+    supported in channels and for messages sent on behalf of a Telegram Business account.
 
     Objects of this class are comparable in terms of equality. Two objects of this class are
     considered equal, if their :attr:`selective` is equal.

telegram/_inline/inlinekeyboardbutton.py

@@ -91,6 +91,7 @@ class InlineKeyboardButton(TelegramObject):
             to the bot when button is pressed, UTF-8
             :tg-const:`telegram.InlineKeyboardButton.MIN_CALLBACK_DATA`-
             :tg-const:`telegram.InlineKeyboardButton.MAX_CALLBACK_DATA` bytes.
+            Not supported for messages sent on behalf of a Telegram Business account.
             If the bot instance allows arbitrary callback data, anything can be passed.
 
             Tip:
@@ -102,25 +103,25 @@ class InlineKeyboardButton(TelegramObject):
             <https://core.telegram.org/bots/webapps>`_  that will be launched when the user presses
             the button. The Web App will be able to send an arbitrary message on behalf of the user
             using the method :meth:`~telegram.Bot.answer_web_app_query`. Available only in
-            private chats between a user and the bot.
+            private chats between a user and the bot. Not supported for messages sent on behalf of
+            a Telegram Business account.
 
             .. versionadded:: 20.0
-        switch_inline_query (:obj:`str`, optional): If set, pressing the button will prompt the
-            user to select one of their chats, open that chat and insert the bot's username and the
-            specified inline query in the input field. Can be empty, in which case just the bot's
-            username will be inserted. This offers an easy way for users to start using your bot
-            in inline mode when they are currently in a private chat with it. Especially useful
-            when combined with ``switch_pm*`` actions - in this case the user will be automatically
-            returned to the chat they switched from, skipping the chat selection screen.
+        switch_inline_query (:obj:`str`, optional): If set, pressing the button will insert the
+            bot's username and the specified inline query in the current chat's input field. May be
+            empty, in which case only the bot's username will be inserted.
+
+            This offers a quick way for the user to open your bot in inline mode in the same chat -
+            good for selecting something from multiple options. Not supported in channels and for
+            messages sent on behalf of a Telegram Business account.
 
             Tip:
                 This is similar to the new parameter :paramref:`switch_inline_query_chosen_chat`,
                 but gives no control over which chats can be selected.
         switch_inline_query_current_chat (:obj:`str`, optional): If set, pressing the button will
-            insert the bot's username and the specified inline query in the current chat's input
-            field. Can be empty, in which case only the bot's username will be inserted. This
-            offers a quick way for the user to open your bot in inline mode in the same chat - good
-            for selecting something from multiple options.
+            prompt the user to select one of their chats of the specified type, open that chat and
+            insert the bot's username and the specified inline query in the input field. Not
+            supported for messages sent on behalf of a Telegram Business account.
         callback_game (:class:`telegram.CallbackGame`, optional): Description of the game that will
             be launched when the user presses the button. This type of button **must** always be
             the **first** button in the first row.
@@ -130,7 +131,8 @@ class InlineKeyboardButton(TelegramObject):
         switch_inline_query_chosen_chat (:obj:`telegram.SwitchInlineQueryChosenChat`, optional):
             If set, pressing the button will prompt the user to select one of their chats of the
             specified type, open that chat and insert the bot's username and the specified inline
-            query in the input field.
+            query in the input field. Not supported for messages sent on behalf of a Telegram
+            Business account.
 
             .. versionadded:: 20.3
 
@@ -159,29 +161,30 @@ class InlineKeyboardButton(TelegramObject):
             to the bot when button is pressed, UTF-8
             :tg-const:`telegram.InlineKeyboardButton.MIN_CALLBACK_DATA`-
             :tg-const:`telegram.InlineKeyboardButton.MAX_CALLBACK_DATA` bytes.
+            Not supported for messages sent on behalf of a Telegram Business account.
         web_app (:obj:`telegram.WebAppInfo`): Optional. Description of the `Web App
             <https://core.telegram.org/bots/webapps>`_  that will be launched when the user presses
             the button. The Web App will be able to send an arbitrary message on behalf of the user
             using the method :meth:`~telegram.Bot.answer_web_app_query`. Available only in
-            private chats between a user and the bot.
+            private chats between a user and the bot. Not supported for messages sent on behalf of
+            a Telegram Business account.
 
             .. versionadded:: 20.0
-        switch_inline_query (:obj:`str`): Optional. If set, pressing the button will prompt the
-            user to select one of their chats, open that chat and insert the bot's username and the
-            specified inline query in the input field. Can be empty, in which case just the bot's
-            username will be inserted. This offers an easy way for users to start using your bot
-            in inline mode when they are currently in a private chat with it. Especially useful
-            when combined with ``switch_pm*`` actions - in this case the user will be automatically
-            returned to the chat they switched from, skipping the chat selection screen.
+        switch_inline_query (:obj:`str`): Optional. If set, pressing the button will insert the
+            bot's username and the specified inline query in the current chat's input field. May be
+            empty, in which case only the bot's username will be inserted.
+
+            This offers a quick way for the user to open your bot in inline mode in the same chat -
+            good for selecting something from multiple options. Not supported in channels and for
+            messages sent on behalf of a Telegram Business account.
 
             Tip:
                 This is similar to the new parameter :paramref:`switch_inline_query_chosen_chat`,
                 but gives no control over which chats can be selected.
         switch_inline_query_current_chat (:obj:`str`): Optional. If set, pressing the button will
-            insert the bot's username and the specified inline query in the current chat's input
-            field. Can be empty, in which case only the bot's username will be inserted. This
-            offers a quick way for the user to open your bot in inline mode in the same chat - good
-            for selecting something from multiple options.
+            prompt the user to select one of their chats of the specified type, open that chat and
+            insert the bot's username and the specified inline query in the input field. Not
+            supported for messages sent on behalf of a Telegram Business account.
         callback_game (:class:`telegram.CallbackGame`): Optional. Description of the game that will
             be launched when the user presses the button. This type of button **must** always be
             the **first** button in the first row.
@@ -191,7 +194,8 @@ class InlineKeyboardButton(TelegramObject):
         switch_inline_query_chosen_chat (:obj:`telegram.SwitchInlineQueryChosenChat`): Optional.
             If set, pressing the button will prompt the user to select one of their chats of the
             specified type, open that chat and insert the bot's username and the specified inline
-            query in the input field.
+            query in the input field. Not supported for messages sent on behalf of a Telegram
+            Business account.
 
             .. versionadded:: 20.3
 

telegram/_inline/inlinequeryresultlocation.py

@@ -89,7 +89,9 @@ class InlineQueryResultLocation(InlineQueryResult):
         live_period (:obj:`int`): Optional. Period in seconds for which the location will be
             updated, should be between
             :tg-const:`telegram.InlineQueryResultLocation.MIN_LIVE_PERIOD` and
-            :tg-const:`telegram.InlineQueryResultLocation.MAX_LIVE_PERIOD`.
+            :tg-const:`telegram.InlineQueryResultLocation.MAX_LIVE_PERIOD` or
+            :tg-const:`telegram.constants.LocationLimit.LIVE_PERIOD_FOREVER` for live
+            locations that can be edited indefinitely.
         heading (:obj:`int`): Optional. For live locations, a direction in which the user is
             moving, in degrees. Must be between
             :tg-const:`telegram.InlineQueryResultLocation.MIN_HEADING` and

telegram/_inline/inputlocationmessagecontent.py

@@ -42,7 +42,9 @@ class InputLocationMessageContent(InputMessageContent):
         live_period (:obj:`int`, optional): Period in seconds for which the location will be
             updated, should be between
             :tg-const:`telegram.InputLocationMessageContent.MIN_LIVE_PERIOD` and
-            :tg-const:`telegram.InputLocationMessageContent.MAX_LIVE_PERIOD`.
+            :tg-const:`telegram.InputLocationMessageContent.MAX_LIVE_PERIOD` or
+            :tg-const:`telegram.constants.LocationLimit.LIVE_PERIOD_FOREVER` for live
+            locations that can be edited indefinitely.
         heading (:obj:`int`, optional): For live locations, a direction in which the user is
             moving, in degrees. Must be between
             :tg-const:`telegram.InputLocationMessageContent.MIN_HEADING` and

telegram/_reply.py

@@ -355,6 +355,7 @@ class ReplyParameters(TelegramObject):
             chat, or in the chat :paramref:`chat_id` if it is specified.
         chat_id (:obj:`int` | :obj:`str`, optional): If the message to be replied to is from a
             different chat, |chat_id_channel|
+            Not supported for messages sent on behalf of a business account.
         allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| Can be
             used only for replies in the same chat and forum topic.
         quote (:obj:`str`, optional): Quoted part of the message to be replied to; 0-1024
@@ -376,6 +377,7 @@ class ReplyParameters(TelegramObject):
             chat, or in the chat :paramref:`chat_id` if it is specified.
         chat_id (:obj:`int` | :obj:`str`): Optional. If the message to be replied to is from a
             different chat, |chat_id_channel|
+            Not supported for messages sent on behalf of a business account.
         allow_sending_without_reply (:obj:`bool`): Optional. |allow_sending_without_reply| Can be
             used only for replies in the same chat and forum topic.
         quote (:obj:`str`): Optional. Quoted part of the message to be replied to; 0-1024

telegram/_replykeyboardmarkup.py

@@ -28,7 +28,8 @@
 
 
 class ReplyKeyboardMarkup(TelegramObject):
-    """This object represents a custom keyboard with reply options.
+    """This object represents a custom keyboard with reply options. Not supported in channels and
+    for messages sent on behalf of a Telegram Business account.
 
     Objects of this class are comparable in terms of equality. Two objects of this class are
     considered equal, if their size of :attr:`keyboard` and all the buttons are equal.

telegram/_replykeyboardremove.py

@@ -29,6 +29,7 @@ class ReplyKeyboardRemove(TelegramObject):
     keyboard and display the default letter-keyboard. By default, custom keyboards are displayed
     until a new keyboard is sent by a bot. An exception is made for one-time keyboards that are
     hidden immediately after the user presses a button (see :class:`telegram.ReplyKeyboardMarkup`).
+    Not supported in channels and for messages sent on behalf of a Telegram Business account.
 
     Note:
         User will not be able to summon this keyboard; if you want to hide the keyboard from