Telegram Stars and payments
manage_telegram_paymentsManage Telegram Stars, invoices, gifts, refunds, and subscriptions for a profile's bot, including balances, payment settings, and confirmed sends or refunds.
Instructions
Telegram Stars, invoices and gifts of the profile's own bot. Fields go in params with the API's names. Reads: stars_balance, star_transactions (offset, limit), get_payment_settings, unanswered_payments (limit: automatic payment answers that failed in the last 30 days), available_gifts, owned_gifts (user_id or chat_id, filters), unique_gift (name). send_invoice (title, description, payload, currency XTR for Stars or a provider currency with provider_token, prices [{label, amount}], photo_url, need_* fields, chat_id; it is posted in the chat) and create_invoice_link (same fields; subscription_period 2592000 makes a 30-day Stars subscription) ask other people to pay the bot. refund_star_payment (user_id, telegram_payment_charge_id; needs confirm, never retried) and edit_star_subscription (user_id, telegram_payment_charge_id, is_canceled; needs confirm). set_payment_settings: automatic pre-checkout answers (pre_checkout off|approve|reject, max_total_amount, allowed_payload_prefixes, error_message, shipping off|static, shipping_options, shipping_countries); they need the bot's updates on (manage_telegram_bot set_updates). send_gift (user_id or chat_id, gift_id, max_star_count, text, idempotency_key; needs confirm) and gift_premium (user_id, month_count 3|6|12, star_count 1000|1500|2500, idempotency_key; needs confirm) SPEND the bot's Stars. Needs the user's approval: call it first without confirmed to get a preview (nothing is sent), show the user exactly what will go out, and repeat the call with confirmed: true only after they approve.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"action": "<action>",
"user": "<user>"
},
"name": "manage_telegram_payments"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| user | Yes | Upload-Post profile name with Telegram connected. | |
| action | Yes | ||
| params | No | Other API fields for this action, with the REST API's own names (snake_case) and shapes. See the description for each action's fields. Leave out what you do not want to change. | |
| confirm | No | The API's own confirmation for deletions and other changes that cannot be undone. Set it to true only after the user has approved that exact change; without it those actions are refused and nothing changes. | |
| confirmed | No | Set to true only after the user has seen the preview this tool returns without it and approved it. Without it nothing is sent. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | No |