Skip to main content


The TelegramPayment action allows you to set up payments in Telegram.

If you want to make Telegram payments using JavaScript code snippets rather than action tags, use replies with the telegramPayment type in $response.replies instead.


providerTokenStringPayment system tokenYou need to obtain a unique token for each payment system in Telegram.Yes
startParameterBooleanAllow clients to forward payment links to other clientstrue — other clients can pay for the service or goods using this link.
false — other clients cannot pay for the service or goods using this link. They will be transferred to the chat with the bot.
paymentTitleStringService or goods titleUse no more than 32 characters.Yes
descriptionStringService or goods descriptionUse no more than 255 characters.Yes
imageUrlStringImage URLYou can attach your service or goods image to the invoice.No
amountStringService or goods priceTelegram sets limits for each currency on the minimum and maximum entered amount.
The amount should contain 12 digits or less.
currencyStringCurrencyThree-letter currency code according to ISO 4217. You can only specify currencies that Telegram and your payment system support.Yes
invoicePayloadStringArbitral invoice detailsThe details will not be shown in the chat. Only the payment system owner will see them.Yes
precheckoutEnabledBooleanCheck the goods availability before checkouttrue — before checkout, the bot will send requests to the service URL specified in precheckoutUrl.
If the goods are out of stock and the service returns a response with an HTTP code other than 2xx, the bot will go to errorState.
false — the bot will not check the goods availability before checkout.
precheckoutUrlStringURL of the service which returns information on whether the requested goods are in stockNo
okStateStringThe state the dialog will switch to if the payment is successfulNo
errorStateStringThe state the dialog will switch to if the parameters are filled incorrectlyThe bot will go to this state if, for example, the specified token is invalid or the price is less than the minimum allowed amount.No
catchAllStateStringThe state the dialog will switch to if the client fails to pay and sends an arbitrary message to the botNo

Payment system token

To receive payments from clients, you need to obtain a unique token of the payment system and specify it in the tag parameters. Create a bot in Telegram before obtaining a token. Follow the steps described in the Telegram as an inbound channel article and return to this one.

  1. Open Telegram and enter BotFather in the search bar.
  2. Send the /mybots command to BotFather.
  3. Choose your bot and select Payments.
  4. Choose a payment system from the list.
  5. Choose one of the payment methods:
    • Test for testing the payment system.
    • Live for setting up a real payment system integration.
  6. You will be redirected to a chatbot for the selected payment system. Start the chatbot.
  7. Follow all the steps the chatbot asks for.
  8. Return to the chat with BotFather.
  9. In the last message from BotFather, you will see a list of connected payment systems and tokens for each of them. Copy the token for the selected payment system.
  10. Paste the token in the providerToken parameter.

Price limits

Telegram sets limits on the minimum and maximum entered amount for each currency. The minimum and maximum amount for each of the currencies roughly correspond to the limit of 1­­–10,000 USD. For each currency except USD, these limits depend on exchange rates and may change over time.

You can find approximate values of the minimum and maximum amount for each supported currency in the Telegram documentation.

How to use

state: TelegramPayment
intent!: /Purchase pass
providerToken = {{$secrets.get("providerToken")}}
startParameter = true
paymentTitle = Her
description = Aurora Theater, December 25, 12 PM
imageUrl =
amount = 15
currency = USD
invoicePayload = Kemp House 60 City Road London EC1V 2NX
okState = /TelegramPayment/PaymentSuccessful
errorState = /TelegramPayment/PaymentFailed
catchAllState = /TelegramPayment/CatchAll

state: PaymentSuccessful
a: The payment was successful. We have sent your ticket to your email address. See you at Conversations!
go!: /SendTickets

state: PaymentFailed
a: The payment failed due to a technical error. Please contact us at to buy tickets.

state: CatchAll
a: The payment was declined. Please check if you have entered the correct card details and try again.
go!: /TelegramPayment

When the client switches to the TelegramPayment state, the following message will appear in the chat:

Telegram Payment