Dec 1, 2024 · Nov 20, 2024 · Nov 25, 2024 · Nov 29, 2024 · Dec 1, 2024
diff --git a/AUTHORS.rst b/AUTHORS.rst
 - `Rahiel Kasim <https://github.com/rahiel>`_
 - `Riko Naka <https://github.com/rikonaka>`_
 - `Rizlas <https://github.com/rizlas>`_
 - `Snehashish Biswas <https://github.com/Snehashish06>`_
 - `Sahil Sharma <https://github.com/sahilsharma811>`_
 - `Sam Mosleh <https://github.com/sam-mosleh>`_
 - `Sascha <https://github.com/saschalalala>`_
diff --git a/examples/paymentbot.py b/examples/paymentbot.py
 # pylint: disable=unused-argument
 # This program is dedicated to the public domain under the CC0 license.

 """Basic example for a bot that can receivepayment fromuser."""
 """Basic example for a bot that can receivepayments fromusers."""

 import logging


 logger = logging.getLogger(__name__)

 # Insert the token from your payment provider.
 # In order to get a provider_token see https://core.telegram.org/bots/payments#getting-a-token
 PAYMENT_PROVIDER_TOKEN = "PAYMENT_PROVIDER_TOKEN"


 async def start_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    """Displays info on how to use the bot."""
    """Provides instructions on how to use the bot."""
    msg = (
        "Use /shipping toget an invoicefor shipping-payment, or /noshipping for an "
        "Use /shipping toreceive an invoicewith shipping included, or /noshipping for an "
        "invoice without shipping."
    )

    await update.message.reply_text(msg)


 async def start_with_shipping_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    """Sends an invoicewithshipping-payment."""
    """Sends an invoicewhich triggers ashipping query."""
    chat_id = update.message.chat_id
    title = "Payment Example"
    description = "PaymentExample using python-telegram-bot"
    #select apayloadjust for you to recognize its the donation from your bot
    description = "Exampleof a payment processusingthepython-telegram-bot library."
    #Uniquepayloadto identify this payment request as being from your bot
    payload = "Custom-Payload"
    # In order to get a provider_token see https://core.telegram.org/bots/payments#getting-a-token
    # Set up the currency.
    # List of supported currencies: https://core.telegram.org/bots/payments#supported-currencies
    currency = "USD"
    #price in dollars
    #Price in dollars
    price = 1
    # price * 100 so as to include 2 decimal points
    # check https://core.telegram.org/bots/payments#supported-currencies for more details
    # Convert price to cents from dollars.
    prices = [LabeledPrice("Test", price * 100)]

    # optionally pass need_name=True, need_phone_number=True,
    # need_email=True, need_shipping_address=True, is_flexible=True
    # Optional parameters like need_shipping_address and is_flexible trigger extra user prompts
    # https://docs.python-telegram-bot.org/en/stable/telegram.bot.html#telegram.Bot.send_invoice
    await context.bot.send_invoice(
        chat_id,
        title,
 async def start_without_shipping_callback(
    update: Update, context: ContextTypes.DEFAULT_TYPE
 ) -> None:
    """Sends an invoice without shipping-payment."""
    """Sends an invoice withoutrequiringshipping details."""
    chat_id = update.message.chat_id
    title = "Payment Example"
    description = "PaymentExample using python-telegram-bot"
    #select apayloadjust for you to recognize its the donation from your bot
    description = "Exampleof a payment processusingthepython-telegram-bot library."
    #Uniquepayloadto identify this payment request as being from your bot
    payload = "Custom-Payload"
    # In order to get a provider_token see https://core.telegram.org/bots/payments#getting-a-token
    currency = "USD"
    #price in dollars
    #Price in dollars
    price = 1
    # price* 100 so astoinclude 2 decimal points
    #Convertprice tocents from dollars.
    prices = [LabeledPrice("Test", price * 100)]

    # optionally pass need_name=True, need_phone_number=True,


 async def shipping_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    """Answers the ShippingQuery withShippingOptions"""
    """Handles the ShippingQuery withavailable shipping options."""
    query = update.shipping_query
    #checkthe payload, is this from your bot?
    #Verify ifthe payload matches, ensure it's from your bot
    if query.invoice_payload != "Custom-Payload":
        #answer False pre_checkout_query
        #If not, respond with an error
        await query.answer(ok=False, error_message="Something went wrong...")
        return

    # First option has a single LabeledPrice
    # Define available shipping options
    # First option with a single price entry
    options = [ShippingOption("1", "Shipping Option A", [LabeledPrice("A", 100)])]
    #second optionhas an array of LabeledPrice objects
    #Second optionwith multiple price entries
    price_list = [LabeledPrice("B1", 150), LabeledPrice("B2", 200)]
    options.append(ShippingOption("2", "Shipping Option B", price_list))
    await query.answer(ok=True, shipping_options=options)


 #after (optional) shipping,it's the pre-checkout
 #After (optional) shipping,process the pre-checkout step
 async def precheckout_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    """AnswersthePreQecheckoutQuery"""
    """Responds tothePreCheckoutQuery as the final confirmation for checkout."""
    query = update.pre_checkout_query
    #checkthe payload, is this from your bot?
    #Verify ifthe payload matches, ensure it's from your bot
    if query.invoice_payload != "Custom-Payload":
        #answer False pre_checkout_query
        #If not, respond with an error
        await query.answer(ok=False, error_message="Something went wrong...")
    else:
        await query.answer(ok=True)


 #finally,aftercontacting thepayment provider...
 #Final callbackaftersuccessfulpayment
 async def successful_payment_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    """Confirms the successful payment."""
    # do something after successfully receiving payment?
    await update.message.reply_text("Thank you for your payment!")
    """Acknowledges successful payment and thanks the user."""
    await update.message.reply_text("Thank you for your payment.")


 def main() -> None:
    """Run the bot."""
    """Starts the bot and sets up handlers."""
    # Create the Application and pass it your bot's token.
    application = Application.builder().token("TOKEN").build()

    #simple start function
    #Start command to display usage instructions
    application.add_handler(CommandHandler("start", start_callback))

    #Add command handler to startthe paymentinvoice
    #Command handlers for startingthe paymentprocess
    application.add_handler(CommandHandler("shipping", start_with_shipping_callback))
    application.add_handler(CommandHandler("noshipping", start_without_shipping_callback))

    #Optional handler if yourproduct requires shipping
    #Handler for shipping query (ifproduct requires shipping)
    application.add_handler(ShippingQueryHandler(shipping_callback))

    # Pre-checkout handlerto final check
    # Pre-checkout handlerfor verifying payment details.
    application.add_handler(PreCheckoutQueryHandler(precheckout_callback))

    #Success!Notifyyour user!
    #Handler for successful payment.Notifythe user that the payment was successful.
    application.add_handler(
        MessageHandler(filters.SUCCESSFUL_PAYMENT, successful_payment_callback)
    )

    #Run the botuntilthe user presses Ctrl-C
    #Start polling for updatesuntilinterrupted (CTRL+C)
    application.run_polling(allowed_updates=Update.ALL_TYPES)


diff --git a/telegram/ext/_aioratelimiter.py b/telegram/ext/_aioratelimiter.py
          necessary in some cases, e.g. the bot may hit a rate limit in one group but might still
          be allowed to send messages in another group.

    Tip:
        With `Bot API 7.1 <https://core.telegram.org/bots/api-changelog#october-31-2024>`_
        (PTB v27.1), Telegram introduced the parameter
        :paramref:`~telegram.Bot.send_message.allow_paid_broadcast`.
        This allows bots to send up to
        :tg-const:`telegram.constants.FloodLimit.PAID_MESSAGES_PER_SECOND` messages per second by
        paying a fee in Telegram Stars.

        .. caution::
            This class currently doesn't take the
            :paramref:`~telegram.Bot.send_message.allow_paid_broadcast` parameter into account.
            This means that the rate limiting is applied just like for any other message.

    Note:
        This class is to be understood as minimal effort reference implementation.
        If you would like to handle rate limiting in a more sophisticated, fine-tuned way, we
diff --git a/telegram/ext/_handlers/commandhandler.py b/telegram/ext/_handlers/commandhandler.py
 class CommandHandler(BaseHandler[Update, CCT, RT]):
    """Handler class to handle Telegram commands.

    Commands are Telegram messages that start with ``/``, optionally followed by an ``@`` and the
    bot's name and/or some additional text. The handler will add a :obj:`list` to the
    :class:`CallbackContext` named :attr:`CallbackContext.args`. It will contain a list of strings,
    which is the text following the command split on single or consecutive whitespace characters.
    Commands are Telegram messages that start with a :attr:`telegram.MessageEntity.BOT_COMMAND`
    (so with ``/``, optionally followed by an ``@`` and the bot's name and/or some additional
    text). The handler will add a :obj:`list` to the :class:`CallbackContext` named
    :attr:`CallbackContext.args`. It will contain a list of strings, which is the text following
    the command split on single or consecutive whitespace characters.

    By default, the handler listens to messages as well as edited messages. To change this behavior
    use :attr:`~filters.UpdateType.EDITED_MESSAGE <telegram.ext.filters.UpdateType.EDITED_MESSAGE>`
        :attr:`telegram.ext.filters.CAPTION` and :class:`telegram.ext.filters.Regex`) to handle
        those messages.

    Note:
        If you want to support a different entity in the beginning, e.g. if a command message is
        wrapped in a :attr:`telegram.MessageEntity.CODE`, use the
        :class:`telegram.ext.PrefixHandler`.

    Warning:
        When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
        attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -111,6 +111,7 @@ The following wonderful people contributed directly or indirectly to this projec
		- `Rahiel Kasim <https://github.com/rahiel>`_
		- `Riko Naka <https://github.com/rikonaka>`_
		- `Rizlas <https://github.com/rizlas>`_
		- `Snehashish Biswas <https://github.com/Snehashish06>`_
		- `Sahil Sharma <https://github.com/sahilsharma811>`_
		- `Sam Mosleh <https://github.com/sam-mosleh>`_
		- `Sascha <https://github.com/saschalalala>`_
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2,7 +2,7 @@
		# pylint: disable=unused-argument
		# This program is dedicated to the public domain under the CC0 license.

		"""Basic example for a bot that can receivepayment fromuser."""
		"""Basic example for a bot that can receivepayments fromusers."""

		import logging

Expand All		@@ -26,36 +26,36 @@

		logger = logging.getLogger(__name__)

		# Insert the token from your payment provider.
		# In order to get a provider_token see https://core.telegram.org/bots/payments#getting-a-token
		PAYMENT_PROVIDER_TOKEN = "PAYMENT_PROVIDER_TOKEN"


		async def start_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
		"""Displays info on how to use the bot."""
		"""Provides instructions on how to use the bot."""
		msg = (
		"Use /shipping toget an invoicefor shipping-payment, or /noshipping for an "
		"Use /shipping toreceive an invoicewith shipping included, or /noshipping for an "
		"invoice without shipping."
		)

		await update.message.reply_text(msg)


		async def start_with_shipping_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
		"""Sends an invoicewithshipping-payment."""
		"""Sends an invoicewhich triggers ashipping query."""
		chat_id = update.message.chat_id
		title = "Payment Example"
		description = "PaymentExample using python-telegram-bot"
		#select apayloadjust for you to recognize its the donation from your bot
		description = "Exampleof a payment processusingthepython-telegram-bot library."
		#Uniquepayloadto identify this payment request as being from your bot
		payload = "Custom-Payload"
		# In order to get a provider_token see https://core.telegram.org/bots/payments#getting-a-token
		# Set up the currency.
		# List of supported currencies: https://core.telegram.org/bots/payments#supported-currencies
		currency = "USD"
		#price in dollars
		#Price in dollars
		price = 1
		# price * 100 so as to include 2 decimal points
		# check https://core.telegram.org/bots/payments#supported-currencies for more details
		# Convert price to cents from dollars.
		prices = [LabeledPrice("Test", price * 100)]

		# optionally pass need_name=True, need_phone_number=True,
		# need_email=True, need_shipping_address=True, is_flexible=True
		# Optional parameters like need_shipping_address and is_flexible trigger extra user prompts
		# https://docs.python-telegram-bot.org/en/stable/telegram.bot.html#telegram.Bot.send_invoice
		await context.bot.send_invoice(
		chat_id,
		title,
Expand All		@@ -75,17 +75,16 @@ async def start_with_shipping_callback(update: Update, context: ContextTypes.DEF
		async def start_without_shipping_callback(
		update: Update, context: ContextTypes.DEFAULT_TYPE
		) -> None:
		"""Sends an invoice without shipping-payment."""
		"""Sends an invoice withoutrequiringshipping details."""
		chat_id = update.message.chat_id
		title = "Payment Example"
		description = "PaymentExample using python-telegram-bot"
		#select apayloadjust for you to recognize its the donation from your bot
		description = "Exampleof a payment processusingthepython-telegram-bot library."
		#Uniquepayloadto identify this payment request as being from your bot
		payload = "Custom-Payload"
		# In order to get a provider_token see https://core.telegram.org/bots/payments#getting-a-token
		currency = "USD"
		#price in dollars
		#Price in dollars
		price = 1
		# price* 100 so astoinclude 2 decimal points
		#Convertprice tocents from dollars.
		prices = [LabeledPrice("Test", price * 100)]

		# optionally pass need_name=True, need_phone_number=True,
Expand All		@@ -96,65 +95,65 @@ async def start_without_shipping_callback(


		async def shipping_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
		"""Answers the ShippingQuery withShippingOptions"""
		"""Handles the ShippingQuery withavailable shipping options."""
		query = update.shipping_query
		#checkthe payload, is this from your bot?
		#Verify ifthe payload matches, ensure it's from your bot
		if query.invoice_payload != "Custom-Payload":
		#answer False pre_checkout_query
		#If not, respond with an error
		await query.answer(ok=False, error_message="Something went wrong...")
		return

		# First option has a single LabeledPrice
		# Define available shipping options
		# First option with a single price entry
		options = [ShippingOption("1", "Shipping Option A", [LabeledPrice("A", 100)])]
		#second optionhas an array of LabeledPrice objects
		#Second optionwith multiple price entries
		price_list = [LabeledPrice("B1", 150), LabeledPrice("B2", 200)]
		options.append(ShippingOption("2", "Shipping Option B", price_list))
		await query.answer(ok=True, shipping_options=options)


		#after (optional) shipping,it's the pre-checkout
		#After (optional) shipping,process the pre-checkout step
		async def precheckout_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
		"""AnswersthePreQecheckoutQuery"""
		"""Responds tothePreCheckoutQuery as the final confirmation for checkout."""
		query = update.pre_checkout_query
		#checkthe payload, is this from your bot?
		#Verify ifthe payload matches, ensure it's from your bot
		if query.invoice_payload != "Custom-Payload":
		#answer False pre_checkout_query
		#If not, respond with an error
		await query.answer(ok=False, error_message="Something went wrong...")
		else:
		await query.answer(ok=True)


		#finally,aftercontacting thepayment provider...
		#Final callbackaftersuccessfulpayment
		async def successful_payment_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
		"""Confirms the successful payment."""
		# do something after successfully receiving payment?
		await update.message.reply_text("Thank you for your payment!")
		"""Acknowledges successful payment and thanks the user."""
		await update.message.reply_text("Thank you for your payment.")


		def main() -> None:
		"""Run the bot."""
		"""Starts the bot and sets up handlers."""
		# Create the Application and pass it your bot's token.
		application = Application.builder().token("TOKEN").build()

		#simple start function
		#Start command to display usage instructions
		application.add_handler(CommandHandler("start", start_callback))

		#Add command handler to startthe paymentinvoice
		#Command handlers for startingthe paymentprocess
		application.add_handler(CommandHandler("shipping", start_with_shipping_callback))
		application.add_handler(CommandHandler("noshipping", start_without_shipping_callback))

		#Optional handler if yourproduct requires shipping
		#Handler for shipping query (ifproduct requires shipping)
		application.add_handler(ShippingQueryHandler(shipping_callback))

		# Pre-checkout handlerto final check
		# Pre-checkout handlerfor verifying payment details.
		application.add_handler(PreCheckoutQueryHandler(precheckout_callback))

		#Success!Notifyyour user!
		#Handler for successful payment.Notifythe user that the payment was successful.
		application.add_handler(
		MessageHandler(filters.SUCCESSFUL_PAYMENT, successful_payment_callback)
		)

		#Run the botuntilthe user presses Ctrl-C
		#Start polling for updatesuntilinterrupted (CTRL+C)
		application.run_polling(allowed_updates=Update.ALL_TYPES)


Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -88,6 +88,19 @@ class AIORateLimiter(BaseRateLimiter[int]):
		necessary in some cases, e.g. the bot may hit a rate limit in one group but might still
		be allowed to send messages in another group.

		Tip:
		With `Bot API 7.1 <https://core.telegram.org/bots/api-changelog#october-31-2024>`_
		(PTB v27.1), Telegram introduced the parameter
		:paramref:`~telegram.Bot.send_message.allow_paid_broadcast`.
		This allows bots to send up to
		:tg-const:`telegram.constants.FloodLimit.PAID_MESSAGES_PER_SECOND` messages per second by
		paying a fee in Telegram Stars.

		.. caution::
		This class currently doesn't take the
		:paramref:`~telegram.Bot.send_message.allow_paid_broadcast` parameter into account.
		This means that the rate limiting is applied just like for any other message.

		Note:
		This class is to be understood as minimal effort reference implementation.
		If you would like to handle rate limiting in a more sophisticated, fine-tuned way, we
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -36,10 +36,11 @@
		class CommandHandler(BaseHandler[Update, CCT, RT]):
		"""Handler class to handle Telegram commands.

		Commands are Telegram messages that start with ``/``, optionally followed by an ``@`` and the
		bot's name and/or some additional text. The handler will add a :obj:`list` to the
		:class:`CallbackContext` named :attr:`CallbackContext.args`. It will contain a list of strings,
		which is the text following the command split on single or consecutive whitespace characters.
		Commands are Telegram messages that start with a :attr:`telegram.MessageEntity.BOT_COMMAND`
		(so with ``/``, optionally followed by an ``@`` and the bot's name and/or some additional
		text). The handler will add a :obj:`list` to the :class:`CallbackContext` named
		:attr:`CallbackContext.args`. It will contain a list of strings, which is the text following
		the command split on single or consecutive whitespace characters.

		By default, the handler listens to messages as well as edited messages. To change this behavior
		use :attr:`~filters.UpdateType.EDITED_MESSAGE <telegram.ext.filters.UpdateType.EDITED_MESSAGE>`
Expand All		@@ -53,6 +54,11 @@ class CommandHandler(BaseHandler[Update, CCT, RT]):
		:attr:`telegram.ext.filters.CAPTION` and :class:`telegram.ext.filters.Regex`) to handle
		those messages.

		Note:
		If you want to support a different entity in the beginning, e.g. if a command message is
		wrapped in a :attr:`telegram.MessageEntity.CODE`, use the
		:class:`telegram.ext.PrefixHandler`.

		Warning:
		When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
		attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
Expand Down