From 89a6eca330d42074a8cef893fb475c9e78c99616 Mon Sep 17 00:00:00 2001
From: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>
Date: Fri, 31 May 2024 13:37:46 +0200
Subject: [PATCH] Misk doc changes from https://t.me/bot_api_changes/136

---
 telegram/_inline/inlinekeyboardbutton.py | 35 ++++++++++++++++--------
 telegram/_keyboardbutton.py              |  3 +-
 2 files changed, 26 insertions(+), 12 deletions(-)

diff --git a/telegram/_inline/inlinekeyboardbutton.py b/telegram/_inline/inlinekeyboardbutton.py
index 9af5d14eda6..d88f222cad7 100644
--- a/telegram/_inline/inlinekeyboardbutton.py
+++ b/telegram/_inline/inlinekeyboardbutton.py
@@ -41,7 +41,8 @@ class InlineKeyboardButton(TelegramObject):
     :attr:`web_app` and :attr:`pay` are equal.
 
     Note:
-        * You must use exactly one of the optional fields. Mind that :attr:`callback_game` is not
+        * Exactly one of the optional fields must be used to specify type of the button.
+        * Mind that :attr:`callback_game` is not
           working as expected. Putting a game short name in it might, but is not guaranteed to
           work.
         * If your bot allows for arbitrary callback data, in keyboards returned in a response
@@ -123,11 +124,17 @@ class InlineKeyboardButton(TelegramObject):
             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.
-        pay (:obj:`bool`, optional): Specify :obj:`True`, to send a Pay button. This type of button
-            **must** always be the **first** button in the first row and can only be used in
-            invoice messages.
+            be launched when the user presses the button
+
+            Note:
+                This type of button **must** always be the first button in the first row.
+        pay (:obj:`bool`, optional): Specify :obj:`True`, to send a Pay button.
+            Substrings ``“⭐️”`` and ``“XTR”`` in the buttons's text will be replaced with a
+            Telegram Star icon.
+
+            Note:
+                This type of button **must** always be the first button in the first row and can
+                only be used in invoice messages.
         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
@@ -186,11 +193,17 @@ class InlineKeyboardButton(TelegramObject):
             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.
-        pay (:obj:`bool`): Optional. Specify :obj:`True`, to send a Pay button. This type of button
-            **must** always be the **first** button in the first row and can only be used in
-            invoice messages.
+            be launched when the user presses the button.
+
+            Note:
+                This type of button **must** always be the first button in the first row.
+        pay (:obj:`bool`): Optional. Specify :obj:`True`, to send a Pay button.
+            Substrings ``“⭐️”`` and ``“XTR”`` in the buttons's text will be replaced with a
+            Telegram Star icon.
+
+            Note:
+                This type of button **must** always be the first button in the first row and can
+                only be used in invoice messages.
         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
diff --git a/telegram/_keyboardbutton.py b/telegram/_keyboardbutton.py
index ad69a176137..0cb4cd82e65 100644
--- a/telegram/_keyboardbutton.py
+++ b/telegram/_keyboardbutton.py
@@ -32,7 +32,8 @@
 
 class KeyboardButton(TelegramObject):
     """
-    This object represents one button of the reply keyboard. For simple text buttons, :obj:`str`
+    This object represents one button of the reply keyboard. At most one of the optional fields
+    must be used to specify type of the button. For simple text buttons, :obj:`str`
     can be used instead of this object to specify text of the button.
 
     Objects of this class are comparable in terms of equality. Two objects of this class are