python-telegram-bot · Bibo-Joshi · May 12, 2025 · May 4, 2025 · May 4, 2025 · May 4, 2025
diff --git a/changes/unreleased/4756.JT5nmUmGRG6qDEh5ScMn5f.toml b/changes/unreleased/4756.JT5nmUmGRG6qDEh5ScMn5f.toml
@@ -6,6 +6,11 @@ This includes the following:
 - Deprecated the class ``telegram.constants.StarTransactions``. Its only member ``telegram.constants.StarTransactions.NANOSTAR_VALUE`` will be replaced by ``telegram.constants.Nanostar.VALUE``.
 - Bot API 9.0 deprecated ``BusinessConnection.can_reply`` in favor of ``BusinessConnection.rights``
 - Bot API 9.0 deprecated ``ChatFullInfo.can_send_gift`` in favor of ``ChatFullInfo.accepted_gift_types``.
+- Bot API 9.0 introduced these new required fields to existing classes:
+  - ``TransactionPartnerUser.transaction_type``
+  - ``ChatFullInfo.accepted_gift_types``
+
+  Passing these values as positional arguments is deprecated. We encourage you to use keyword arguments instead, as the the signature will be updated in a future release.
 
 These deprecations are backward compatible, but we strongly recommend to update your code to use the new members.
 """
@@ -37,6 +42,10 @@ uid = "4773"
 author_uid = "aelkheir"
 closes_threads = []
 [[pull_requests]]
+uid = "4781"
+author_uid = "aelkheir"
+closes_threads = []
+[[pull_requests]]
 uid = "4782"
 author_uid = "Bibo-Joshi"
 closes_threads = []
diff --git a/docs/source/inclusions/bot_methods.rst b/docs/source/inclusions/bot_methods.rst
@@ -394,6 +394,8 @@
       - Used for obtaining the bot's Telegram Stars transactions
     * - :meth:`~telegram.Bot.refund_star_payment`
       - Used for refunding a payment in Telegram Stars
+    * - :meth:`~telegram.Bot.gift_premium_subscription`
+      - Used for gifting Telegram Premium to another user.
 
 .. raw:: html
 

diff --git a/telegram/_bot.py b/telegram/_bot.py
@@ -9368,6 +9368,83 @@ async def set_message_reaction(
             api_kwargs=api_kwargs,
         )
 
+    async def gift_premium_subscription(
+        self,
+        user_id: int,
+        month_count: int,
+        star_count: int,
+        text: Optional[str] = None,
+        text_parse_mode: ODVInput[str] = DEFAULT_NONE,
+        text_entities: Optional[Sequence["MessageEntity"]] = None,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> bool:
+        """
+        Gifts a Telegram Premium subscription to the given user.
+
+        .. versionadded:: NEXT.VERSION
+
+        Args:
+            user_id (:obj:`int`): Unique identifier of the target user who will receive a Telegram
+                Premium subscription.
+            month_count (:obj:`int`): Number of months the Telegram Premium subscription will be
+                active for the user; must be one of
+                :tg-const:`telegram.constants.PremiumSubscription.MONTH_COUNT_THREE`,
+                :tg-const:`telegram.constants.PremiumSubscription.MONTH_COUNT_SIX`,
+                or :tg-const:`telegram.constants.PremiumSubscription.MONTH_COUNT_TWELVE`.
+            star_count (:obj:`int`): Number of Telegram Stars to pay for the Telegram Premium
+               subscription; must be
+               :tg-const:`telegram.constants.PremiumSubscription.STARS_THREE_MONTHS`
+               for :tg-const:`telegram.constants.PremiumSubscription.MONTH_COUNT_THREE` months,
+               :tg-const:`telegram.constants.PremiumSubscription.STARS_SIX_MONTHS`
+               for :tg-const:`telegram.constants.PremiumSubscription.MONTH_COUNT_SIX` months,
+               and :tg-const:`telegram.constants.PremiumSubscription.STARS_TWELVE_MONTHS`
+               for :tg-const:`telegram.constants.PremiumSubscription.MONTH_COUNT_TWELVE` months.
+            text (:obj:`str`, optional): Text that will be shown along with the service message
+                about the subscription;
+                0-:tg-const:`telegram.constants.PremiumSubscription.MAX_TEXT_LENGTH` characters.
+            text_parse_mode (:obj:`str`, optional): Mode for parsing entities.
+                See :class:`telegram.constants.ParseMode` and
+                `formatting options <https://core.telegram.org/bots/api#formatting-options>`__ for
+                more details. Entities other than :attr:`~MessageEntity.BOLD`,
+                :attr:`~MessageEntity.ITALIC`, :attr:`~MessageEntity.UNDERLINE`,
+                :attr:`~MessageEntity.STRIKETHROUGH`, :attr:`~MessageEntity.SPOILER`, and
+                :attr:`~MessageEntity.CUSTOM_EMOJI` are ignored.
+            text_entities (Sequence[:class:`telegram.MessageEntity`], optional): A list of special
+                entities that appear in the gift text. It can be specified instead of
+                :paramref:`text_parse_mode`. Entities other than :attr:`~MessageEntity.BOLD`,
+                :attr:`~MessageEntity.ITALIC`, :attr:`~MessageEntity.UNDERLINE`,
+                :attr:`~MessageEntity.STRIKETHROUGH`, :attr:`~MessageEntity.SPOILER`, and
+                :attr:`~MessageEntity.CUSTOM_EMOJI` are ignored.
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+
+        Raises:
+            :class:`telegram.error.TelegramError`
+        """
+        data: JSONDict = {
+            "user_id": user_id,
+            "month_count": month_count,
+            "star_count": star_count,
+            "text": text,
+            "text_entities": text_entities,
+            "text_parse_mode": text_parse_mode,
+        }
+        return await self._post(
+            "giftPremiumSubscription",
+            data,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
     async def get_business_connection(
         self,
         business_connection_id: str,
@@ -11236,6 +11313,8 @@ def to_dict(self, recursive: bool = True) -> JSONDict:  # noqa: ARG002
     """Alias for :meth:`get_user_chat_boosts`"""
     setMessageReaction = set_message_reaction
     """Alias for :meth:`set_message_reaction`"""
+    giftPremiumSubscription = gift_premium_subscription
+    """Alias for :meth:`gift_premium_subscription`"""
     getBusinessAccountGifts = get_business_account_gifts
     """Alias for :meth:`get_business_account_gifts`"""
     getBusinessAccountStarBalance = get_business_account_star_balance

diff --git a/telegram/_payment/stars/transactionpartner.py b/telegram/_payment/stars/transactionpartner.py
@@ -281,55 +281,115 @@ class TransactionPartnerUser(TransactionPartner):
     """Describes a transaction with a user.
 
     Objects of this class are comparable in terms of equality. Two objects of this class are
-    considered equal, if their :attr:`user` are equal.
+    considered equal, if their :attr:`user` and :attr:`transaction_type` are equal.
 
     .. versionadded:: 21.4
 
+    .. versionchanged:: NEXT.VERSION
+       Equality comparison now includes the new required argument :paramref:`transaction_type`,
+       introduced in Bot API 9.0.
+
     Args:
+        transaction_type (:obj:`str`): Type of the transaction, currently one of
+            :tg-const:`telegram.constants.TransactionPartnerUser.INVOICE_PAYMENT` for payments via
+            invoices, :tg-const:`telegram.constants.TransactionPartnerUser.PAID_MEDIA_PAYMENT`
+            for payments for paid media,
+            :tg-const:`telegram.constants.TransactionPartnerUser.GIFT_PURCHASE` for gifts sent by
+            the bot, :tg-const:`telegram.constants.TransactionPartnerUser.PREMIUM_PURCHASE`
+            for Telegram Premium subscriptions gifted by the bot,
+            :tg-const:`telegram.constants.TransactionPartnerUser.BUSINESS_ACCOUNT_TRANSFER` for
+            direct transfers from managed business accounts.
+
+            .. versionadded:: NEXT.VERSION
         user (:class:`telegram.User`): Information about the user.
         affiliate (:class:`telegram.AffiliateInfo`, optional): Information about the affiliate that
-            received a commission via this transaction
+            received a commission via this transaction. Can be available only for
+            :tg-const:`telegram.constants.TransactionPartnerUser.INVOICE_PAYMENT`
+            and :tg-const:`telegram.constants.TransactionPartnerUser.PAID_MEDIA_PAYMENT`
+            transactions.
 
             .. versionadded:: 21.9
-        invoice_payload (:obj:`str`, optional): Bot-specified invoice payload.
+        invoice_payload (:obj:`str`, optional): Bot-specified invoice payload. Can be available
+            only for :tg-const:`telegram.constants.TransactionPartnerUser.INVOICE_PAYMENT`
+            transactions.
         subscription_period (:class:`datetime.timedelta`, optional): The duration of the paid
-            subscription
+            subscription. Can be available only for
+            :tg-const:`telegram.constants.TransactionPartnerUser.INVOICE_PAYMENT` transactions.
 
             .. versionadded:: 21.8
         paid_media (Sequence[:class:`telegram.PaidMedia`], optional): Information about the paid
-            media bought by the user.
+            media bought by the user. for
+            :tg-const:`telegram.constants.TransactionPartnerUser.PAID_MEDIA_PAYMENT`
+            transactions only.
 
             .. versionadded:: 21.5
-        paid_media_payload (:obj:`str`, optional): Bot-specified paid media payload.
+        paid_media_payload (:obj:`str`, optional): Bot-specified paid media payload. Can be
+            available only for
+            :tg-const:`telegram.constants.TransactionPartnerUser.PAID_MEDIA_PAYMENT` transactions.
 
             .. versionadded:: 21.6
-        gift (:class:`telegram.Gift`, optional): The gift sent to the user by the bot
+        gift (:class:`telegram.Gift`, optional): The gift sent to the user by the bot; for
+            :tg-const:`telegram.constants.TransactionPartnerUser.GIFT_PURCHASE` transactions only.
 
             .. versionadded:: 21.8
+        premium_subscription_duration (:obj:`int`, optional): Number of months the gifted Telegram
+            Premium subscription will be active for; for
+            :tg-const:`telegram.constants.TransactionPartnerUser.PREMIUM_PURCHASE`
+            transactions only.
+
+            .. versionadded:: NEXT.VERSION
 
     Attributes:
         type (:obj:`str`): The type of the transaction partner,
             always :tg-const:`telegram.TransactionPartner.USER`.
+        transaction_type (:obj:`str`): Type of the transaction, currently one of
+            :tg-const:`telegram.constants.TransactionPartnerUser.INVOICE_PAYMENT` for payments via
+            invoices, :tg-const:`telegram.constants.TransactionPartnerUser.PAID_MEDIA_PAYMENT`
+            for payments for paid media,
+            :tg-const:`telegram.constants.TransactionPartnerUser.GIFT_PURCHASE` for gifts sent by
+            the bot, :tg-const:`telegram.constants.TransactionPartnerUser.PREMIUM_PURCHASE`
+            for Telegram Premium subscriptions gifted by the bot,
+            :tg-const:`telegram.constants.TransactionPartnerUser.BUSINESS_ACCOUNT_TRANSFER` for
+            direct transfers from managed business accounts.
+
+            .. versionadded:: NEXT.VERSION
         user (:class:`telegram.User`): Information about the user.
         affiliate (:class:`telegram.AffiliateInfo`): Optional. Information about the affiliate that
-            received a commission via this transaction
+            received a commission via this transaction. Can be available only for
+            :tg-const:`telegram.constants.TransactionPartnerUser.INVOICE_PAYMENT`
+            and :tg-const:`telegram.constants.TransactionPartnerUser.PAID_MEDIA_PAYMENT`
+            transactions.
 
             .. versionadded:: 21.9
-        invoice_payload (:obj:`str`): Optional. Bot-specified invoice payload.
+        invoice_payload (:obj:`str`): Optional. Bot-specified invoice payload. Can be available
+            only for :tg-const:`telegram.constants.TransactionPartnerUser.INVOICE_PAYMENT`
+            transactions.
         subscription_period (:class:`datetime.timedelta`): Optional. The duration of the paid
-            subscription
+            subscription. Can be available only for
+            :tg-const:`telegram.constants.TransactionPartnerUser.INVOICE_PAYMENT` transactions.
 
             .. versionadded:: 21.8
         paid_media (tuple[:class:`telegram.PaidMedia`]): Optional. Information about the paid
-            media bought by the user.
+            media bought by the user. for
+            :tg-const:`telegram.constants.TransactionPartnerUser.PAID_MEDIA_PAYMENT`
+            transactions only.
 
             .. versionadded:: 21.5
-        paid_media_payload (:obj:`str`): Optional. Bot-specified paid media payload.
+        paid_media_payload (:obj:`str`): Optional. Bot-specified paid media payload. Can be
+            available only for
+            :tg-const:`telegram.constants.TransactionPartnerUser.PAID_MEDIA_PAYMENT` transactions.
 
             .. versionadded:: 21.6
-        gift (:class:`telegram.Gift`): Optional. The gift sent to the user by the bot
+        gift (:class:`telegram.Gift`): Optional. The gift sent to the user by the bot; for
+            :tg-const:`telegram.constants.TransactionPartnerUser.GIFT_PURCHASE` transactions only.
 
             .. versionadded:: 21.8
+        premium_subscription_duration (:obj:`int`): Optional. Number of months the gifted Telegram
+            Premium subscription will be active for; for
+            :tg-const:`telegram.constants.TransactionPartnerUser.PREMIUM_PURCHASE`
+            transactions only.
+
+            .. versionadded:: NEXT.VERSION
 
     """
 
@@ -339,7 +399,9 @@ class TransactionPartnerUser(TransactionPartner):
         "invoice_payload",
         "paid_media",
         "paid_media_payload",
+        "premium_subscription_duration",
         "subscription_period",
+        "transaction_type",
         "user",
     )
 
@@ -352,11 +414,18 @@ def __init__(
         subscription_period: Optional[dtm.timedelta] = None,
         gift: Optional[Gift] = None,
         affiliate: Optional[AffiliateInfo] = None,
+        premium_subscription_duration: Optional[int] = None,
+        # temporarily optional to account for changed signature
+        transaction_type: Optional[str] = None,
         *,
         api_kwargs: Optional[JSONDict] = None,
     ) -> None:
         super().__init__(type=TransactionPartner.USER, api_kwargs=api_kwargs)
 
+        # tags: deprecated NEXT.VERSION, bot api 9.0
+        if transaction_type is None:
+            raise TypeError("`transaction_type` is a required argument since Bot API 9.0")
+
         with self._unfrozen():
             self.user: User = user
             self.affiliate: Optional[AffiliateInfo] = affiliate
@@ -365,10 +434,13 @@ def __init__(
             self.paid_media_payload: Optional[str] = paid_media_payload
             self.subscription_period: Optional[dtm.timedelta] = subscription_period
             self.gift: Optional[Gift] = gift
+            self.premium_subscription_duration: Optional[int] = premium_subscription_duration
+            self.transaction_type: str = transaction_type
 
             self._id_attrs = (
                 self.type,
                 self.user,
+                self.transaction_type,
             )
 
     @classmethod

diff --git a/telegram/_user.py b/telegram/_user.py
@@ -1698,6 +1698,46 @@ async def send_gift(
             api_kwargs=api_kwargs,
         )
 
+    async def gift_premium_subscription(
+        self,
+        month_count: int,
+        star_count: int,
+        text: Optional[str] = None,
+        text_parse_mode: ODVInput[str] = DEFAULT_NONE,
+        text_entities: Optional[Sequence["MessageEntity"]] = None,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> bool:
+        """Shortcut for::
+
+             await bot.gift_premium_subscription(user_id=update.effective_user.id, *args, **kwargs)
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.gift_premium_subscription`.
+
+        .. versionadded:: NEXT.VERSION
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+        """
+        return await self.get_bot().gift_premium_subscription(
+            user_id=self.id,
+            month_count=month_count,
+            star_count=star_count,
+            text=text,
+            text_parse_mode=text_parse_mode,
+            text_entities=text_entities,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
     async def send_copy(
         self,
         from_chat_id: Union[str, int],