Actions5
Overview
This node interacts with the Telegram Stars payments API, enabling various operations related to Telegram Stars payments. It supports sending invoices, answering pre-checkout queries, refunding star payments, retrieving star transactions, and getting the current bot's star balance. This node is useful for automating payment workflows within Telegram bots, such as billing users, handling payment confirmations, processing refunds, and monitoring transaction history.
Use Case Examples
- Send an invoice to a user for a product or service using Telegram Stars.
- Respond to pre-checkout queries to confirm or reject payments.
- Issue refunds for successful star payments.
- Retrieve a list of star transactions for auditing or reporting purposes, with options to paginate results by offset and limit parameters, e.g., get the last 100 transactions starting from a specific offset position in the transaction list (between 1-100).
Properties
| Name | Meaning |
|---|---|
| Operation | Specifies the Telegram Stars API operation to perform, such as sending an invoice, answering pre-checkout queries, refunding payments, getting transactions, or retrieving the bot's star balance. |
| Chat ID | Unique identifier for the target chat or username of the target channel (required for sending invoices). |
| Title | Product name, 1-32 characters (required for sending invoices). |
| Description | Product description, 1-255 characters (required for sending invoices). |
| Payload | Bot-defined invoice payload, 1-128 bytes (required for sending invoices). |
| Currency | Three-letter ISO 4217 currency code. Use "XTR" for Telegram Stars (required for sending invoices). |
| Price Label | Portion label for the price (required for sending invoices). |
| Price Amount | Price of the product in the smallest units of the currency (required for sending invoices). |
| Additional Fields (Send Invoice) | Optional additional parameters for sending invoices, such as message thread ID, provider data, photo URL, photo size, photo width, photo height, disable notification, protect content, reply to message ID, and allow sending without reply. |
| Pre-Checkout Query ID | Unique identifier for the query to be answered (required for answering pre-checkout queries). |
| OK | Boolean indicating whether everything is alright (true) or if there is an error (false) when answering pre-checkout queries. |
| Error Message | Error message in human-readable form, required if OK is false when answering pre-checkout queries. |
| User ID | Identifier of the user whose payment will be refunded (required for refunding star payments). |
| Telegram Payment Charge ID | Telegram payment identifier (required for refunding star payments). |
| Additional Fields (Get Star Transactions) | Optional parameters for retrieving star transactions, including offset (number of transactions to skip) and limit (maximum number of transactions to retrieve, between 1-100). |
Output
JSON
chat_id- Identifier of the chat where the invoice or message was sent.title- Title of the product or service invoiced.description- Description of the product or service invoiced.payload- Bot-defined invoice payload.currency- Currency code used for the payment.prices- Array of price portions with labels and amounts.pre_checkout_query_id- Identifier for the pre-checkout query answered.ok- Boolean indicating success or failure of the pre-checkout query response.error_message- Error message if the pre-checkout query response failed.user_id- User identifier for refund operations.telegram_payment_charge_id- Telegram payment charge identifier for refund operations.offset- Number of transactions to skip when retrieving star transactions.limit- Maximum number of star transactions retrieved.balance- Current star balance of the bot.
Dependencies
- Telegram Stars API
- An API key credential for Telegram Stars API authentication
Troubleshooting
- Ensure the 'Price Label' is provided and not empty when sending invoices; otherwise, the node throws an error.
- Ensure the 'Price Amount' is a positive number when sending invoices; negative or zero values cause errors.
- When answering pre-checkout queries with 'ok' set to false, provide a human-readable 'Error Message' to avoid errors.
- Check that required parameters like 'Chat ID', 'User ID', and 'Telegram Payment Charge ID' are correctly set for their respective operations.
- If the node fails due to API request issues, verify the Telegram Stars API credentials and network connectivity.
Links
- Telegram Stars Payments API - Official documentation for Telegram Stars payments integration.