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#64dfc926 flags:# refund:flags.3?true pending:flags.4?true failed:flags.6?true gift:flags.10?true reaction:flags.11?true id:string stars:StarsAmount 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> subscription_period:flags.12?int giveaway_post_id:flags.13?int stargift:flags.14?StarGift floodskip_number:flags.15?int starref_commission_permille:flags.16?int starref_peer:flags.17?Peer starref_amount:flags.17?StarsAmount = StarsTransaction;
payments.starsStatus#6c9ce8ed flags:# balance:StarsAmount subscriptions:flags.1?Vector<StarsSubscription> subscriptions_next_offset:flags.2?string subscriptions_missing_balance:flags.4?long history:flags.3?Vector<StarsTransaction> next_offset:flags.0?string chats:Vector<Chat> users:Vector<User> = payments.StarsStatus;
updateStarsBalance#4e80a379 balance:StarsAmount = Update;
---functions---
payments.getStarsStatus#104fcfa7 peer:InputPeer = payments.StarsStatus;
payments.getStarsTransactions#69da4557 flags:# inbound:flags.0?true outbound:flags.1?true ascending:flags.2?true subscription_id:flags.3?string 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#febe5491 flags:# withdrawal_enabled:flags.0?true current_balance:StarsAmount available_balance:StarsAmount overall_revenue:StarsAmount 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.
The price in US dollars of 1000 Telegram Stars can be fetched using the stars_usd_sell_rate_x1000 config parameter ».
The Star topup page should also be activated, if some conditions are met, when the user clicks on a topup deep link ».
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#7998c914 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.
Users can now directly support their favorite channels and content creators by sending them Telegram Stars using a new Star reaction.
Channel owners receive 100% of the stars — and can convert them into Toncoin cryptocurrency rewards or subsidized ads.
See here » for the full flow.
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.
Channel administrators can now create special invite links that allow joining a channel in exchange for a monthly payment in Telegram Stars.
Subscribing to a channel using a paid invite link will transfer Telegram Stars to the channel's balance.
See here » for the full flow.
Star giveaways are similar to normal giveaways, with the only difference that instead of giving away gifts or Telegram Premium subscriptions, the giveaway will automatically distribute Telegram Stars among the winners.
See here » for the full flow.
Users can send Gifts to their friends. The recipients of gifts can display them on their profile pages or turn them into Telegram Stars.
See here » for the full flow.
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.
By withdrawing one thousand stars, the user will receive the equivalent of stars_usd_withdraw_rate_x1000 US dollars, as specified by the client configuration ».
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.