Telegram Stars are virtual items that allow users to purchase digital goods and services from bots and mini apps inside the Telegram ecosystem, send gifts to content creators on the Telegram platform, and more.
This page describes the methods used to buy, use and withdraw Telegram Stars, as well as view detailed revenue stats and make purchases using Telegram Stars.
Clients should disable Telegram Stars support for the current user if the stars_purchase_blocked field is equal to true » due to regional limitations.
inputStarsTransaction#206ae6d1 flags:# refund:flags.0?true id:string = InputStarsTransaction;
starsTransactionPeerAppStore#b457b375 = StarsTransactionPeer;
starsTransactionPeerPlayMarket#7b560a0b = StarsTransactionPeer;
starsTransactionPeerPremiumBot#250dbaf8 = StarsTransactionPeer;
starsTransactionPeerFragment#e92fd902 = StarsTransactionPeer;
starsTransactionPeer#d80da15d peer:Peer = StarsTransactionPeer;
starsTransactionPeerAds#60682812 = StarsTransactionPeer;
starsTransactionPeerUnsupported#95f2bfe4 = StarsTransactionPeer;
starsTransaction#2db5418f flags:# refund:flags.3?true pending:flags.4?true failed:flags.6?true gift:flags.10?true id:string stars:long date:int peer:StarsTransactionPeer title:flags.0?string description:flags.1?string photo:flags.2?WebDocument transaction_date:flags.5?int transaction_url:flags.5?string bot_payload:flags.7?bytes msg_id:flags.8?int extended_media:flags.9?Vector<MessageMedia> = StarsTransaction;
payments.starsStatus#8cf4ee60 flags:# balance:long history:Vector<StarsTransaction> next_offset:flags.0?string chats:Vector<Chat> users:Vector<User> = payments.StarsStatus;
updateStarsBalance#0fb85198 balance:long = Update;
---functions---
payments.getStarsStatus#104fcfa7 peer:InputPeer = payments.StarsStatus;
payments.getStarsTransactions#97938d5a flags:# inbound:flags.0?true outbound:flags.1?true ascending:flags.2?true peer:InputPeer offset:string limit:int = payments.StarsStatus;
payments.getStarsTransactionsByID#27842d2e peer:InputPeer id:Vector<InputStarsTransaction> = payments.StarsStatus;Use payments.getStarsStatus to get the current stars balance of the current account (with peer=inputPeerSelf), or the stars balance of the bot or channel specified in peer.
The method will also return the last 5 star transactions ».
To return all star transactions » (and optionally search using filters), use payments.getStarsTransactions, paginating through the transactions passing the returned next_offset (if set) to offset as usual.
payments.getStarsTransactionsByID may be used to fetch info about specific Telegram Star transactions (or refunds) using their IDs, passed as inputStarsTransaction constructors.
Changes in the star balance (through topups or purchases) will be notified by the server via an updateStarsBalance update.
starsRevenueStatus#79342946 flags:# withdrawal_enabled:flags.0?true current_balance:long available_balance:long overall_revenue:long next_withdrawal_at:flags.1?int = StarsRevenueStatus;
payments.starsRevenueStats#c92bb73b revenue_graph:StatsGraph status:StarsRevenueStatus usd_rate:double = payments.StarsRevenueStats;
updateStarsRevenueStatus#a584b019 peer:Peer status:StarsRevenueStatus = Update;
---functions---
payments.getStarsRevenueStats#d91ffad6 flags:# dark:flags.0?true peer:InputPeer = payments.StarsRevenueStats;Telegram Star revenue statistics may be fetched by bot owners, and by channel admins if the channelFull.can_view_stars_revenue flag is set.
Use payments.getStarsRevenueStats to fetch statistics about earned Telegram Stars; the returned StatsGraph graphs can be rendered as described here ».
Specifically:
revenue_graph - Star revenue graph (number of earned stars)status - Current balance, current withdrawable balance and overall earned Telegram Starsusd_rate - Current conversion rate of Telegram Stars to USDThe server will emit an updateStarsRevenueStatus every time the balance changes; if the client is currently in the Monetization tab of the channel or bot, this update should apply the new balances (contained in the update), and refresh the transaction list using payments.getStarsTransactions as specified here ».
starsTopupOption#bd915c0 flags:# extended:flags.1?true stars:long store_product:flags.0?string currency:string amount:long = StarsTopupOption;
starsGiftOption#5e0589f1 flags:# extended:flags.1?true stars:long store_product:flags.0?string currency:string amount:long = StarsGiftOption;
inputStorePaymentStarsTopup#dddd0f56 stars:long currency:string amount:long = InputStorePaymentPurpose;
inputStorePaymentStarsGift#1d741ef7 user_id:InputUser stars:long currency:string amount:long = InputStorePaymentPurpose;
inputInvoiceStars#65f00ce3 purpose:InputStorePaymentPurpose = InputInvoice;
---functions---
payments.getStarsTopupOptions#c00ec7d3 = Vector<StarsTopupOption>;
payments.getStarsGiftOptions#d3c96bc8 flags:# user_id:flags.0?InputUser = Vector<StarsGiftOption>;To purchase telegram stars for ourselves, first invoke the payments.getStarsTopupOptions method, to obtain a list of topup options as starsTopupOption constructors.
To purchase telegram stars for a friend, first invoke the payments.getStarsGiftOptions method, to obtain a list of gift options as starsGiftOption constructors.
Note: Star gifting functionality should only be enabled if the stars_gifts_enabled » flag is equal to true.
Once the user has chosen a specific star topup/gift option, invoke payments.getPaymentForm, passing an inputInvoiceStars, with either inputStorePaymentStarsTopup or inputStorePaymentStarsGift, populated with the values from the chosen starsTopupOption/starsGiftOption.
Then, follow the invoice payment flow as described in the payments documentation ».
More alternative payment flows are also available:
For gifts, once the payment is successfully processed, the user to which the gift was sent will automatically receive a messageService from the user that sent the gift, containing a messageActionGiftStars constructor with further info about the price and duration of the gifted Telegram Stars.
Clients should display this message, along with a sticker from the inputStickerSetPremiumGifts stickerset: here's an example.
payments.paymentFormStars#7bf6b15c flags:# form_id:long bot_id:long title:string description:string photo:flags.5?WebDocument invoice:Invoice users:Vector<User> = payments.PaymentForm;
payments.paymentReceiptStars#dabbf83a flags:# date:int bot_id:long title:string description:string photo:flags.2?WebDocument invoice:Invoice currency:string total_amount:long transaction_id:string users:Vector<User> = payments.PaymentReceipt;
---functions---
payments.sendStarsForm#02bb731d flags:# form_id:long invoice:InputInvoice = payments.PaymentResult;
payments.refundStarsCharge#25ae8f4a user_id:InputUser charge_id:string = Updates;The full flow to follow to make purchases using Telegram Stars is described along the traditional payment flow in the payments documentation »: all invoices and constructors working with currency amounts will use the currency code XTR, and the amounts will be in Telegram Stars.
Telegram Stars are used to pay for paid media, which may be posted on channels by administrators as specified here ».
Purchasing paid media will transfer Telegram Stars to the channel's balance.
Channel owners can then withdraw Stars as Toncoin », or use Stars to place ads for the channel ».
Star revenue statistics and balance information is also available to channel owners.
Telegram Stars are also used to pay for digital services in bots, using keyboardButtonBuy and the usual payment flow », with currency="XTR".
Purchasing paid media will transfer Telegram Stars to the bot's balance.
Bot owners can then withdraw Stars as Toncoin », or use Stars to place ads for the channel ».
Star revenue statistics and balance information is also available to bot owners.
payments.starsRevenueWithdrawalUrl#1dab80b7 url:string = payments.StarsRevenueWithdrawalUrl;
---functions---
payments.getStarsRevenueWithdrawalUrl#13bbe8b3 peer:InputPeer stars:long password:InputCheckPasswordSRP = payments.StarsRevenueWithdrawalUrl;To withdraw funds from the star balance of a channel or bot we own, invoke payments.getStarsRevenueWithdrawalUrl, passing the current account's 2FA password as an InputCheckPasswordSRP constructor, generated as specified here ».
Only the channel/bot owner can invoke this method, and only if the balance is bigger than or equal to stars_revenue_withdrawal_min » and the status.withdrawal_enabled flag returned by payments.getStarsRevenueStats is set.
The method will return a unique URL to a Fragment page where the user will be able to specify and submit the address of the TON wallet where the funds will be sent.
starsTransactionPeerAds#60682812 = StarsTransactionPeer;
payments.starsRevenueAdsAccountUrl#394e7f21 url:string = payments.StarsRevenueAdsAccountUrl;
---functions---
payments.getStarsRevenueAdsAccountUrl#d1d7efc5 peer:InputPeer = payments.StarsRevenueAdsAccountUrl;Channel/bot owners may place Telegram advertisements for channels/bots they own using the Telegram Ad platform, paying using the Stars currently available on the bot/channel's balance at a special rate with a 30% discount – creating a cost-effective way of reaching new users.
To use Stars for ads, go to your bot's or channels' Balance or Monetization section and tap 'Buy Ads'.
Clicking on the button should invoke payments.getStarsRevenueAdsAccountUrl (passing the bot/channel in peer).
The returned url will lead to a page where the user will be able to place ads for the channel/bot passed in peer.
Transactions for ad payments will be of type starsTransactionPeerAds.