diff --git a/data/core.telegram.org/bots/api.html b/data/core.telegram.org/bots/api.html
index cc32354757..b4c4b96f88 100644
--- a/data/core.telegram.org/bots/api.html
+++ b/data/core.telegram.org/bots/api.html
@@ -50,6 +50,31 @@ To learn how to create…">
Subscribe to @BotNews to be the first to know about the latest updates and join the discussion in @BotTalk
Allowed sending invoices to group, supergroup and channel chats.
+
Added the fields max_tip_amount and suggested_tip_amounts to the method sendInvoice to allow adding optional tips to the payment.
+
The parameter start_parameter of the method sendInvoice became optional. If the parameter isn't specified, the invoice can be paid directly from forwarded messages.
+
Added the field chat_type to the class InlineQuery, containing the type of the chat, from which the inline request was sent.
Fixed an error in sendChatAction documentation to correctly mention “record_voice” and “upload_voice” instead of “record_audio” and “upload_audio” for related to voice note actions. Old action names will still work for backward compatibility.
+
+
+
+
WARNING! After the next Bot API update (Bot API 5.3) there will be a one-time change of the value of the field file_unique_id in objects of the type PhotoSize and of the fields small_file_unique_id and big_file_unique_id in objects of the type ChatPhoto.
+
+
+
+
WARNING! Service messages about non-bot users joining the chat will be soon removed from large groups. We recommend using the “chat_status” update as a replacement.
+
+
+
+
WARNING! After one of the upcoming Bot API updates, user identifiers will become bigger than 2^31 - 1 and it will be no longer possible to store them in a signed 32-bit integer type. User identifiers will have up to 52 significant bits, so a 64-bit integer or double-precision float type would still be safe for storing them. Please make sure that your code can correctly handle such user identifiers.
+
+
March 9, 2021
Bot API 5.1
Added two new update types
@@ -877,6 +902,11 @@ To learn how to create…">
Optional. Service message. A user in the chat triggered another user's proximity alert while sharing Live Location.
This object represents a service message about a voice chat scheduled in the chat.
+
+
+
+
Field
+
Type
+
Description
+
+
+
+
+
start_date
+
Integer
+
Point in time (Unix timestamp) when the voice chat is supposed to be started by a chat administrator
+
+
+
VoiceChatStarted
This object represents a service message about a voice chat started in the chat. Currently holds no information.
VoiceChatEnded
@@ -2839,7 +2887,7 @@ pre-formatted fixed-width code block written in the Python programming language
Escaping inside entities is not allowed, so entity must be closed first and reopened again: use _snake_\__case_ for italic snake_case and *2*\**2=4* for bold 2*2=4.
forwardMessage
-
Use this method to forward messages of any kind. On success, the sent Message is returned.
+
Use this method to forward messages of any kind. Service messages can't be forwarded. On success, the sent Message is returned.
@@ -2877,7 +2925,7 @@ pre-formatted fixed-width code block written in the Python programming language
copyMessage
-
Use this method to copy messages of any kind. The method is analogous to the method forwardMessage, but the copied message doesn't have a link to the original message. Returns the MessageId of the sent message on success.
+
Use this method to copy messages of any kind. Service messages and invoice messages can't be copied. The method is analogous to the method forwardMessage, but the copied message doesn't have a link to the original message. Returns the MessageId of the sent message on success.
@@ -5651,11 +5699,6 @@ pre-formatted fixed-width code block written in the Python programming language
Optional. Sender location, only for bots that request user location
-
-
query
String
Text of the query (up to 256 characters)
@@ -5665,6 +5708,16 @@ pre-formatted fixed-width code block written in the Python programming language
String
Offset of the results to be returned, can be controlled by the bot
+
+
chat_type
+
String
+
Optional. Type of the chat, from which the inline query was sent. Can be either “sender” for a private chat with the inline query sender, “private”, “group”, “supergroup”, or “channel”. The chat type should be always known for requests sent from official clients and most third-party clients, unless the request was sent from a secret chat
Price breakdown, a JSON-serialized list of components (e.g. product price, tax, discount, delivery cost, delivery tax, bonus, etc.)
+
+
+
max_tip_amount
+
Integer
+
Optional. The maximum accepted amount for tips in the smallest units of the currency (integer, not float/double). For example, for a maximum tip of US$ 1.45 pass max_tip_amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). Defaults to 0
+
+
+
suggested_tip_amounts
+
Array of Integer
+
Optional. A JSON-serialized array of suggested amounts of tip in the smallest units of the currency (integer, not float/double). At most 4 suggested tip amounts can be specified. The suggested tip amounts must be positive, passed in a strictly increased order and must not exceed max_tip_amount.
+
+
+
provider_data
+
String
+
Optional. A JSON-serialized object for data about the invoice, which will be shared with the payment provider. A detailed description of the required fields should be provided by the payment provider.
+
+
+
photo_url
+
String
+
Optional. URL of the product photo for the invoice. Can be a photo of the goods or a marketing image for a service. People like it better when they see what they are paying for.
+
+
+
photo_size
+
Integer
+
Optional. Photo size
+
+
+
photo_width
+
Integer
+
Optional. Photo width
+
+
+
photo_height
+
Integer
+
Optional. Photo height
+
+
+
need_name
+
Boolean
+
Optional. Pass True, if you require the user's full name to complete the order
+
+
+
need_phone_number
+
Boolean
+
Optional. Pass True, if you require the user's phone number to complete the order
+
+
+
need_email
+
Boolean
+
Optional. Pass True, if you require the user's email address to complete the order
+
+
+
need_shipping_address
+
Boolean
+
Optional. Pass True, if you require the user's shipping address to complete the order
+
+
+
send_phone_number_to_provider
+
Boolean
+
Optional. Pass True, if user's phone number should be sent to provider
+
+
+
send_email_to_provider
+
Boolean
+
Optional. Pass True, if user's email address should be sent to provider
+
+
+
is_flexible
+
Boolean
+
Optional. Pass True, if the final price depends on the shipping method
+
+
+
ChosenInlineResult
Represents a result of an inline query that was chosen by the user and sent to their chat partner.
@@ -7327,9 +7494,9 @@ pre-formatted fixed-width code block written in the Python programming language
chat_id
-
Integer
+
Integer or String
Yes
-
Unique identifier for the target private chat
+
Unique identifier for the target chat or username of the target channel (in the format @channelusername)
title
@@ -7356,12 +7523,6 @@ pre-formatted fixed-width code block written in the Python programming language
Unique deep-linking parameter that can be used to generate this invoice when used as a start parameter
-
-
currency
String
Yes
@@ -7374,6 +7535,24 @@ pre-formatted fixed-width code block written in the Python programming language
Price breakdown, a JSON-serialized list of components (e.g. product price, tax, discount, delivery cost, delivery tax, bonus, etc.)
+
max_tip_amount
+
Integer
+
Optional
+
The maximum accepted amount for tips in the smallest units of the currency (integer, not float/double). For example, for a maximum tip of US$ 1.45 pass max_tip_amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). Defaults to 0
+
+
+
suggested_tip_amounts
+
Array of Integer
+
Optional
+
A JSON-serialized array of suggested amounts of tips in the smallest units of the currency (integer, not float/double). At most 4 suggested tip amounts can be specified. The suggested tip amounts must be positive, passed in a strictly increased order and must not exceed max_tip_amount.
+
+
+
start_parameter
+
String
+
Optional
+
Unique deep-linking parameter. If left empty, forwarded copies of the sent message will have a Pay button, allowing multiple users to pay directly from the forwarded message, using the same invoice. If non-empty, forwarded copies of the sent message will have a URL button with a deep link to the bot (instead of a Pay button), with the value used as the start parameter
+
+
provider_data
String
Optional
diff --git a/data/core.telegram.org/bots/payments.html b/data/core.telegram.org/bots/payments.html
index 1e144aa685..d829316dc7 100644
--- a/data/core.telegram.org/bots/payments.html
+++ b/data/core.telegram.org/bots/payments.html
@@ -4,12 +4,10 @@
Bot Payments API
-
+
-
+
@@ -47,30 +45,50 @@ Note: This article is intended for bot developers. If you're…">
-
You can accept payments from Telegram users via Telegram Bots.
+
Telegram Bot Payments are a free and open platform that allows sellers to accept payments for goods and services from Telegram users. Telegram doesn't collect payment information and takes no commission.
-
Note: This article is intended for bot developers. If you're looking for a general overview of Telegram Payments, check out the Telegram blog. Also, visit the MTProto payment documentation for a technical overview of payments from the user's perspective.
+
Note: This article is intended for bot developers and store owners. If you're looking for a general overview of Telegram Payments, check out the Telegram blog.
If you are new to Telegram bots and would like to learn how to create and set up a bot, please consult our Introduction to Bots and Bot FAQ.
-
Introducing Payments
-
Telegram bots can accept payments for goods and services from users as of Bot API v.3.0. Users will need Telegram v.4.0 or higher to pay for your goods and services.
-
How does this work?
-
From the user's perspective the payments system is completely seamless. Merchant bots can send specially formatted invoice messages to users. Such invoice messages feature a photo and description of the product along with a prominent Pay button. Tapping this button opens a special payment interface in the Telegram app. In this interface, users are prompted for additional details like shipping info, phone number, or email address.
-
Once they've entered all the necessary info, it is forwarded to the merchant bot. The bot can offer several shipping options for physical goods based on the address. When ready, users can enter their credit card info or choose one of their saved cards — and pay for the product. Telegram also supports Apple Pay and Google Pay. Once the transaction is done, the merchant bot sends a receipt message that contains payment details along with shipping and delivery information.
-
-
-
-
How do you process payments?
-
Telegram does not process payments from users and instead relies on different payment providers around the world. It is the payment providers that handle and store all sensitive information, like credit card details. Neither Telegram nor the bot developers have access to it. For the moment we support payments from more than 200 countries via the the following payment providers:
+
+
Users need to update to Telegram 7.7 or higher to use Payments 2.0 (for Telegram Desktop, 2.7.2 or higher). Older mobile apps released after May 2017 support basic payments in chats with bots.
+
+
How does this work?
+
You create a bot that offers goods and services to Telegram users. Merchant bots can send specially formatted invoice messages to users, groups or channels. If your bot supports inline mode, users can also send invoices to other chats via the bot, including to one-on-one chats with other users.
+
+
+
+
+
Invoice messages feature a photo and description of the product along with a prominent Pay button. Tapping this button opens a special payment interface in the Telegram app. In this interface, users can choose a tip amount (if allowed by the merchant) and enter additional details like shipping info, phone number, or email address.
+
The bot can offer several shipping options for physical goods based on the delivery address. When ready, users enter their credit card info or choose a saved card — and pay for the product. Telegram also supports Apple Pay and Google Pay. Once the transaction is done, the merchant bot can send a receipt message with payment details, shipping and delivery information.
Telegram does not process payments from users and instead relies on different payment providers around the world. It is the payment providers that handle and store all sensitive information, like credit card details. Neither Telegram nor the bot developers have access to it.
+
For the moment we support payments from more than 200 countries via the the following payment providers:
More providers are coming, stay tuned to @BotNews for updates.
-
How do I join as a payment provider?
-
If you work for a company that provides services similar to standalone accounts in Stripe Connect, please let us know via @BotSupport (kindly include the hashtag #paymentsprovider in your message).
-
How much do you charge?
-
Telegram does not charge any commission for using the Payments API. Note though, that most payment providers will have their own commissions. For example, Stripe in the US charges 2.9% + 30¢ per successful card charge (see the Stripe website for more details on pricing).
-
What can my bot sell?
-
Telegram does not impose any limits on what products or services your bot can offer. But please note that you must comply with the rules of the payments provider you choose in our system. E.g., Stripe has a special page for prohibited businesses – you may want to consult that one before you start selling harvested organs.
-
Special Note: Due to Apple's limitations, bot developers are currently not allowed to accept payments for digital goods and virtual services from iOS users.
-
How are disputes handled?
-
Telegram acts as a messenger between the paying user, the bot developer, and their chosen payment system. The user sends their credit card details directly to the payment system. Then the payment system's response and the shipping details entered by the user are passed to the bot developer so that they can process the order.
-
Since Telegram doesn‘t process the payments, we don’t store and can‘t access any sensitive data. Due to this structure, it is impossible for Telegram to handle complaints or cashbacks – any disputed payments are the responsibility of the bot developers, payment providers, and banks that participated in the exchange.
+
We continue expanding this list, follow @BotNews for updates.
If you work for a company that provides services similar to standalone accounts in Stripe Connect, please let us know via @BotSupport (include the hashtag #paymentsprovider in your message).
+
The Payments API
-
Now let's look at payments via Telegram's Bot API in more detail. To start accepting payments, you need a Telegram bot, obviously. Have a chat with BotFather to create a bot if you haven't got one already.
+
This section explores payments via Telegram's Bot API in more detail.
Connecting Payments
-
Now you have a merchant bot that wants to offer goods or services to Telegram users. Let's call it @merchantbot in this document. First stop is to choose and connect a payment provider, you can find the list of supported providers above.
+
To start accepting payments, you need a Telegram bot. Use BotFather to create a bot if you don't have one already.
+
Now you have a merchant bot that can offer goods or services to Telegram users. Let's call it @merchantbot in this document. The first stop is to choose and connect a payment provider, you can find the list of supported providers above.
Getting a Token
-
Use the /mybots command in the chat with BotFather and choose the @merchantbot that will be offering goods or services. Go to Bot Settings > Payments. Choose a provider, and you will be redirected to the relevant bot. Enter the required details so that the payments provider is connected successfully, go back to the chat with Botfather. The message will now show available providers. Each will have a name, a token, and the date the provider was connected. You will use the token when working with the Bot API.
+
+
Use the /mybots command in the chat with BotFather and choose the @merchantbot that will be offering goods or services.
+
Go to Bot Settings > Payments.
+
Choose a provider, and you will be redirected to the relevant bot.
+
Enter the required details so that the payments provider is connected successfully, go back to the chat with Botfather.
+
The message will now show available providers. Each will have a name, a token, and the date the provider was connected.
+
You will use the token when working with the Bot API.
While you're still developing and testing payments for your bot, use the “Stripe TEST MODE” provider. When in this mode, you can make payments without actually billing any accounts. Real cards can't be used in test mode, but you can use test cards like 4242 4242 4242 4242 (full list here). You can switch between test mode and live mode as many times as you want, but please see the live checklist before you go live.
-
Please note that when your merchant bot is working in test mode, it will only be able to send invoices to those Telegram users that are mutual contacts with the account of the bot's creator. So make sure that those who will help you test the payments functionality are in your contacts list.
+
While you're still developing and testing payments for your bot, use the “Stripe TEST MODE” provider. When in this mode, you can make payments without actually billing any accounts. Real cards can't be used in test mode, but you can use test cards like 4242 4242 4242 4242 (full list here). You can switch between test mode and live mode as many times as you want, but please see the live checklistbefore you go live.
Step-by-Step Process
+
+
See Bot API: Payments for the complete list of available methods and objects.
+
1. Create Invoice
-
The user contacts @merchantbot and requests to purchase something. The bot forms an invoice message with a description of the goods or service, amount to be paid, as well as requested shipping info.
-
Use the sendInvoice method to do this. The provider_token parameter is where you put the token value that you've obtained earlier via Botfather. It is possible for one merchant bot to use several different tokens for different users or different goods and services.
-
An invoice message with a pay button can only be sent to a private chat with the user. Groups and channels are not supported. The resulting invoice message will look like this:
+
The user contacts @merchantbot and requests to purchase something. The bot forms an invoice message with a description of the goods or service, amount to be paid, and requested shipping info. There are two ways of creating an invoice:
+
A. Bot Invoice
+
Use the sendInvoice method to generate an invoice and send it to a chat. The provider_token parameter is where you put the token value that you've obtained earlier via Botfather. It is possible for one merchant bot to use several different tokens for different users or different goods and services.
+
As of Payments 2.0, invoice messages with a pay button can be sent to chats of any type: private chats with the user, groups, or channels. The resulting invoice message will look like this:
-
-
Invoice in Chat
+
+
Bot Invoice
-
2. Shipping info and other details (optional step)
+
B. Inline Invoice
+
If @merchantbot supports inline mode, you can use inputInvoiceMessageContent to allow users to share invoices for your goods and services to their one-on-one chats with friends, or to their groups and channels. These invoices will have a Pay button that can be used multiple times.
+
+
+
Inline Invoice
+
+
2. Choose Forwarding Behavior
+
As of Payments 2.0 there are two ways for handling forwarded copies of your invoices, controlled by the parameter start_parameter in the sendInvoice method.
+
+
A. Multi-chat invoice. Forwarded copies show a Pay button, which multiple users can press and attempt to pay for the goods or services. Inline invoices are always multi-chat invoices.
+
B. Single-chat invoice. Invoice can only be paid from the chat to which it was sent, forwarded copies show a URL button with a deep link to the bot. The deep link can be used to generate a similar invoice in the chat with the bot, to show an error message, or for other purposes. More info on Deep Linking »
+
+
If a single-chat invoice is sent to the chat with @merchantbot, it can only be paid once. If a single-chat invoice is sent to any other chat, it can be paid many times by many users.
+
+
To get a better understanding of how this works, try toggling the “Pay from Forwards” parameter when creating invoices with our demo @ShopBot.
+
+
Regardless of whether or not the Pay button is available in an invoice, the merchant bot always has the power to decide whether or not to accept new payments for a particular invoice.
+
3. Tips (optional step)
+
If the max_tip_amount parameter is set to above 0, users can add a tip to their payment. You can use the parameter suggested_tip_amounts to suggest particular amounts that you feel will be relevant for the invoice.
+
+
+
Adding Tips
+
+
4. Shipping info and other details (optional step)
The user specifies shipping information or other info requested by the bot. This could be the user's full name, an email address, a phone number in international format, or a full postal address for delivery.
-
+
Shipping Info
-
3. Offer delivery options based on shipping address (optional step)
+
5. Offer delivery options based on shipping address (optional step)
If a shipping address was requested and you included the parameter is_flexible, the Bot API will send an Update with a shipping_query field to the bot. The bot must respond using answerShippingQuery either with a list of possible delivery options and the relevant delivery prices, or with an error (for example, if delivery to the specified address is not possible).
-
4. Select delivery option (optional step)
+
+
Tip: It is recommended that the merchant bot confirms availability of the goods/services at this step – to let the user know in case they are no longer available. This is especially important if you are using multi-chat, inline or single-chat, multi-use invoices.
+
+
6. Select delivery option (optional step)
The user selects a delivery option from the list (the overall amount to be paid may change at this point) and proceeds to checkout.
-
+
Choose Delivery Option
-
5. Pre-Checkout
+
7. Pre-Checkout
The user enters their payment information and presses the final pay button. At this moment the Bot API sends an Update with the field pre_checkout_query to the bot that contains all the available information about the order. Your bot must reply using answerPrecheckoutQuery within 10 seconds after receiving this update or the transaction is canceled.
-
The bot may return an error if it can't process the order for any reason. We highly recommend specifying a reason for failure to complete the order in human readable form (e.g. "Sorry, we're all out of rubber ducks! Would you be interested in a steel bear instead?"). Telegram will display this reason to the user.
-
6. Checkout
+
The bot may return an error if it can't process the order for any reason. We highly recommend specifying a reason for failure to complete the order in human readable form (e.g. "Sorry, we're all out of rubber ducks! Would you be interested in a cast iron bear instead?"). Telegram will display this reason to the user.
+
+
Warning: As of Payments 2.0, it is critical to make sure your bot only accepts multiple payments when the order can be processed correctly. This is especially important if you are using multi-chat, inline or single-chat, multi-use invoices.
+
+
8. Checkout
In case the bot confirms the order, Telegram requests the payment provider to complete the transaction. If the payment information was entered correctly and the payment goes through, the API will send a receipt message of the type successful_payment from the user. Once your bot receives this message, it should proceed with delivering the goods or services purchased by the user.
-
For the user, the Invoice message in the UI becomes a Receipt — they can open this receipt at any time and see all the details of the transaction:
+
If the invoice message was sent in the chat with @merchantbot, it becomes a Receipt in the UI for the user — they can open this receipt at any time and see all the details of the transaction:
-
+
Receipt
-
Going Viral: Deep Linking
-
Note the arrow button on the right of the receipt message on the screenshot above. This quick forwarding button allows the user to select multiple friends, groups, or channels and send the message to them immediately. Thanks to this button, your goods and services can spread virally — the resulting message will have a button that leads users to your bot and asks it to create a similar invoice.
-
For the quick forwarding button to work correctly, all your invoice messages must contain a start_parameter for creating a new invoice. More info on Deep Linking »
+
If the message was sent to any other chat, the Pay button remains and can be used again. It is up to the merchant bot whether to actually accept multiple payments.
Going Live
Once you've tested everything and confirmed that your payments implementation works, you're ready to switch to LIVE MODE. To do this, go to BotFather > /mybots > select @merchantbot > Bot Settings / Payments and enable Stripe LIVE MODE. You will get a token that has the string :LIVE: in the middle, e.g. 123:LIVE:XXXX. Do not give this token to any third parties!
Before your merchant bot goes into live mode, please ensure the following:
@@ -149,7 +198,26 @@ Note: This article is intended for bot developers. If you're…">
Make sure that your server hardware and software is stable. Use backups to make sure that you don't lose data about your users' payments.
Make sure that you have completed the live checklist for your selected payments provider as well as this one.
-
Supported Currencies
+
+
FAQ
+
How do I join as a payment provider?
+
If you work for a company that provides services similar to standalone accounts in Stripe Connect, please let us know via @BotSupport (kindly include the hashtag #paymentsprovider in your message).
+
How much do you charge?
+
Telegram does not charge any commission for using the Payments API. Note though, that most payment providers will have their own commissions. For example, Stripe in the US charges 2.9% + 30¢ per successful card charge (see the Stripe website for more details on pricing).
+
Do I need a bot to accept payments?
+
Yes. If you are not a developer, you will need to either hire someone to make a bot for you (recommended), or use a bot created by a third-party company. We advise extreme caution when using services of bots that process payments for you – Telegram doesn't maintain any such bots and doesn't endorse any of the third-party bots offering these services.
+
What can my bot sell?
+
Telegram does not impose any limits on what products or services your bot can offer. But please note that you must comply with the rules of the payments provider you choose in our system. E.g., Stripe has a special page for prohibited businesses – you may want to consult that one before you start selling harvested organs.
+
Special Note: Due to Apple's limitations, bot developers are currently not allowed to accept payments for digital goods and virtual services from iOS users.
+
How are disputes handled?
+
Telegram acts as a messenger between the paying user, the bot developer, and their chosen payment system. The user sends their credit card details directly to the payment system. Then the payment system's response and the shipping details entered by the user are passed to the bot developer so that they can process the order.
+
Since Telegram doesn‘t process the payments, we don’t store and can‘t access any sensitive data. Due to this structure, it is impossible for Telegram to handle complaints or cashbacks – any disputed payments are the responsibility of the bot developers, payment providers, and banks that participated in the exchange.
Telegram payments currently support the currencies listed below (here's a JSON version in case you need it).
If you're using Stripe as the payments provider, supported currencies may vary depending on the country you have specified in your Stripe account (more info).
The minimum and maximum amounts for each of the currencies roughly correspond to the limit of US$ 1-10000. The amount must be expressed in 12 digits or less, so the maximum value will be correspondingly lower for some lower-value currencies. Note that for each currency except USD these limits depend on exchange rates and may change over time (plan ahead for this when you implement limits in your code).
WARNING!
WARNING!