Telegram 明星

Telegram Stars 是虚拟物品，用户可以使用它从 Telegram 生态系统内的机器人和小程序购买数字商品和服务，向 Telegram 平台上的内容创作者赠送礼物等等。

本页面介绍了购买、使用和提现Telegram Stars 的方法，以及查看详细的收入统计数据和使用 Telegram Stars 进行购买的方法。

由于区域限制， 如果stars_purchase_blocked 字段等于true »，则客户端应禁用当前用户的 Telegram Stars 支持。

余额和交易记录 

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#13659eb0 flags:# refund:flags.3?true pending:flags.4?true failed:flags.6?true gift:flags.10?true reaction:flags.11?true stargift_upgrade:flags.18?true business_transfer:flags.21?true stargift_resale:flags.22?true posts_search:flags.24?true stargift_prepaid_upgrade:flags.25?true id:string amount: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 paid_messages:flags.19?int premium_gift_months:flags.20?int ads_proceeds_from_date:flags.23?int ads_proceeds_to_date:flags.23?int = 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#4ea9b3bf flags:# ton:flags.0?true peer:InputPeer = payments.StarsStatus;payments.getStarsTransactions#69da4557 flags:# inbound:flags.0?true outbound:flags.1?true ascending:flags.2?true ton:flags.4?true subscription_id:flags.3?string peer:InputPeer offset:string limit:int = payments.StarsStatus;payments.getStarsTransactionsByID#2dca16b8 flags:# ton:flags.0?true peer:InputPeer id:Vector<InputStarsTransaction> = payments.StarsStatus;

使用payments.getStarsStatus获取当前帐户（peer=inputPeerSelf）的当前星星余额，或获取指定机器人或频道的星星余额peer。

如果设置了channelFull./userFull.标志，频道/机器人管理员也可以通过设置上面列出的所有方法的标志来获取频道/机器人广告收入交易历史记录和余额（以纳吨为单位1/1_000_000_000，即 toncoin 的 th）。toncan_view_revenuecan_view_revenue

该方法还会返回最近的 5 笔星级交易 »。
要返回所有星级交易 »（并可选择使用筛选器进行搜索），请使用payments.getStarsTransactions ，并像往常一样分页浏览交易，并将返回的值next_offset（如果已设置）传递给它。offset

payments.getStarsTransactionsByID可用于使用作为inputStarsTransaction构造函数传递的 ID 获取有关特定 Telegram Star 交易（或退款）的信息。

星星余额的变化（通过充值或购买）将由服务器通过updateStarsBalance更新通知。

收入统计 

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#6c207376 flags:# top_hours_graph:flags.0?StatsGraph 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 ton:flags.1?true peer:InputPeer = payments.StarsRevenueStats;

Telegram Star 的收入统计数据可以由机器人所有者获取，如果设置了channelFull标志，频道管理员也可以获取。can_view_stars_revenue

如果设置了channelFull./userFull.标志，频道/机器人管理员也可以通过设置该标志来获取以纳吨（吨币的十分之一）为单位的频道/机器人广告收入统计数据。1/1_000_000_000toncan_view_revenuecan_view_revenue

使用payments.getStarsRevenueStats获取有关赚取的 Telegram Stars/nanoton 的统计信息；返回的StatsGraph图表可以按照此处所述进行渲染»。

具体来说：

服务器会在余额每次发生变化时发出updateStarsRevenueStatus；如果客户端当前位于频道或机器人的“变现”选项卡中，则此更新应应用新的余额（包含在更新中），并使用payments.getStarsTransactions刷新交易列表，如这里所述»。

购买或赠送星星 

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#f9a2a6cb flags:# stars:long currency:string amount:long spend_purpose_peer:flags.0?InputPeer = 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>;

要为自己购买 Telegram 星星，首先调用payments.getStarsTopupOptions方法，以获取starTopupOption构造函数形式的充值选项列表。

要为朋友购买 Telegram 星星，首先调用payments.getStarsGiftOptions方法，以获取starsGiftOption构造函数形式的礼物选项列表。

注意：只有当stars_gifts_enabled »标志等于 true 时，才应启用星星赠送功能。

用户选择特定的星星充值/礼物选项后，调用payments.getPaymentForm，传递inputInvoiceStars，其中inputStorePaymentStarsTopup或inputStorePaymentStarsGift填充了所选starsTopupOption/starsGiftOption中的值。

inputStorePaymentStarsTopup»spend_purpose_peer应该填充因资金不足而发起充值流程的对等方（例如，用于机器人支付的机器人、用于付费媒体/互动的频道等）；如果在尝试花费超过账户余额中可用星星数量的金额时未发起充值流程，则不要填充此标志。

然后，按照付款文档中描述的发票付款流程进行操作 »。

还有更多替代支付方式可供选择：

对于赠送的礼物，一旦付款成功处理，收礼用户将自动收到来自赠送用户的messageService ，其中包含一个messageActionGiftStars构造函数，其中包含有关赠送的 Telegram Stars 的价格和持续时间的更多信息。
客户端应显示此消息，并附上来自inputStickerSetPremiumGifts 贴纸集的贴纸：这里有一个示例。

stars_usd_sell_rate_x1000可以使用配置参数»获取1000 Telegram Stars的美元价格。

当满足某些条件时，当用户点击充值深度链接时，也应该激活 Star 充值页面»。

星级评定 

starsRating#1b0e4f07 flags:# level:int current_level_stars:long stars:long next_level_stars:flags.0?long = StarsRating;userFull#c577b5ad flags:# blocked:flags.0?true phone_calls_available:flags.4?true phone_calls_private:flags.5?true can_pin_message:flags.7?true has_scheduled:flags.12?true video_calls_available:flags.13?true voice_messages_forbidden:flags.20?true translations_disabled:flags.23?true stories_pinned_available:flags.26?true blocked_my_stories_from:flags.27?true wallpaper_overridden:flags.28?true contact_require_premium:flags.29?true read_dates_private:flags.30?true flags2:# sponsored_enabled:flags2.7?true can_view_revenue:flags2.9?true bot_can_manage_emoji_status:flags2.10?true display_gifts_button:flags2.16?true id:long about:flags.1?string settings:PeerSettings personal_photo:flags.21?Photo profile_photo:flags.2?Photo fallback_photo:flags.22?Photo notify_settings:PeerNotifySettings bot_info:flags.3?BotInfo pinned_msg_id:flags.6?int common_chats_count:int folder_id:flags.11?int ttl_period:flags.14?int theme:flags.15?ChatTheme private_forward_name:flags.16?string bot_group_admin_rights:flags.17?ChatAdminRights bot_broadcast_admin_rights:flags.18?ChatAdminRights wallpaper:flags.24?WallPaper stories:flags.25?PeerStories business_work_hours:flags2.0?BusinessWorkHours business_location:flags2.1?BusinessLocation business_greeting_message:flags2.2?BusinessGreetingMessage business_away_message:flags2.3?BusinessAwayMessage business_intro:flags2.4?BusinessIntro birthday:flags2.5?Birthday personal_channel_id:flags2.6?long personal_channel_message:flags2.6?int stargifts_count:flags2.8?int starref_program:flags2.11?StarRefProgram bot_verification:flags2.12?BotVerification send_paid_messages_stars:flags2.14?long disallowed_gifts:flags2.15?DisallowedGiftsSettings stars_rating:flags2.17?StarsRating stars_my_pending_rating:flags2.18?StarsRating stars_my_pending_rating_date:flags2.18?int main_tab:flags2.20?ProfileTab saved_music:flags2.21?Document = UserFull;

Telegram 个人资料现在会显示一个徽章，该徽章会根据用户与 Telegram Stars 完成的成功交易总数给出数值评级。

它会突出显示您的 Telegram 等级，并帮助频道所有者看到您在推荐帖子和其他请求方面值得信赖。

购买礼物、发送付费消息以及用星星赞助推荐帖子都能提升您的评分。但是，如果您退还购买的星星或将礼物兑换成星星，您的评分将会下降。

评分包含在starsRating构造 函数中，来自userFull。stars_rating

level星级评分由（可能为负整数）和（可能为负整数）表示rating：用户可以通过达到某些阈值来升级或降级rating。

我们还可能在userFull中看到待定的星级评分。该 评分stars_my_pending_rating仅供我们自己查看，并将应用于userFull。stars_my_pending_rating_date

stars_rating_learnmore_url将包含一个 URL，该 URL 可以显示给用户，指向一个包含有关星级评分系统的更多信息的页面。

使用星星 

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;

使用 Telegram Stars 进行购买的完整流程与支付文档中的传统支付流程一致»：所有涉及货币金额的发票和构造函数都将使用货币代码XTR，金额将以 Telegram Stars 为单位。

付费媒体

Telegram Stars 用于支付付费媒体费用，管理员可以按照此处的规定将其发布到频道中 »。

购买付费媒体会将 Telegram Stars 转入频道余额。
频道所有者随后可以将 Stars 提现为 Toncoin »，或使用 Stars 为频道投放广告 »。

频道所有者还可以查看明星收入统计数据和余额信息。

付费信息

Telegram Stars 可用于向已设置付费消息的用户和频道发送消息 »，即每发送一条消息都需要付费。

购买付费媒体会将 Telegram 星星转入频道或用户的余额。

付费反应

用户现在可以通过新的星形表情功能，直接向他们喜爱的频道和内容创作者发送 Telegram 星形来支持他们。

频道所有者可获得 100% 的星星，并可将其兑换成 Toncoin 加密货币奖励或补贴广告。

请点击这里查看完整流程。

推荐帖子

Telegram 为频道管理员提供了一个强大的盈利功能：推荐帖子。

请点击这里查看完整流程。

机器人支付

Telegram Stars 也被用于在机器人中使用keyboardButtonBuy和常规支付流程来支付数字服务»，使用currency="XTR"。

购买付费媒体会将 Telegram Stars 转入机器人的余额。
机器人所有者随后可以将 Stars 提现为 Toncoin »，或使用 Stars 为频道投放广告 »。

机器人所有者还可以查看明星收入统计数据和余额信息。

明星推荐

开发者可以为其小程序开通联盟计划——允许内容创作者、其他小程序开发者和任何 Telegram 用户推广该小程序，并从他们推荐的人的购买中赚取佣金。

请点击这里»查看完整流程的更多信息。

星级订阅

机器人和频道可以创建订阅，定期向用户收取一定数量的Telegram 星星，以换取内容和服务。

请点击这里查看完整流程。

明星赠品

星形奖品赠送活动与普通赠送活动类似，唯一的区别在于，赠送活动不会赠送礼物或Telegram Premium 会员资格，而是会自动向获奖者分发 Telegram 星星。

请点击这里查看完整流程。

星光礼物

用户可以向好友赠送礼物。收礼人可以将礼物展示在个人资料页面上，或将其升级为 Telegram 明星。

请点击这里查看完整流程。

提取收入 

payments.starsRevenueWithdrawalUrl#1dab80b7 url:string = payments.StarsRevenueWithdrawalUrl;---functions---payments.getStarsRevenueWithdrawalUrl#2433dc92 flags:# ton:flags.0?true peer:InputPeer amount:flags.1?long password:InputCheckPasswordSRP = payments.StarsRevenueWithdrawalUrl;

要从我们拥有的频道或机器人的星币余额中提取资金，请调用payments.getStarsRevenueWithdrawalUrl，并将当前帐户的2FA 密码作为InputCheckPasswordSRP构造函数传递，该构造函数按照此处的规定生成 »。

要提取频道/机器人的广告收入，请以相同的方式调用相同的方法，同时设置标志ton。

只有频道/机器人所有者才能调用此方法，并且只有当余额大于或等于stars_revenue_withdrawal_min »并且payments.getStarsRevenueStatsstatus.withdrawal_enabled返回的标志已设置时才能调用。

stars_revenue_withdrawal_max指定可从频道或机器人余额中提取的最大Telegram Stars数量。要提取更多 Stars，请重新开始提现流程。

该方法将返回一个指向Fragment页面的唯一 URL，用户可以在该页面上指定并提交 TON 钱包地址，资金将发送到该钱包。

提现一千颗星星，用户将收到等值的stars_usd_withdraw_rate_x1000美元，具体金额由客户端配置决定。

付费广告 

starsTransactionPeerAds#60682812 = StarsTransactionPeer;payments.starsRevenueAdsAccountUrl#394e7f21 url:string = payments.StarsRevenueAdsAccountUrl;---functions---payments.getStarsRevenueAdsAccountUrl#d1d7efc5 peer:InputPeer = payments.StarsRevenueAdsAccountUrl;

频道/机器人所有者可以使用 Telegram 广告平台，以30% 的折扣，用机器人/频道余额中现有的星星支付，为自己拥有的频道/机器人投放 Telegram 广告——这是一种经济高效的触达新用户的方式。

要使用星星投放广告，请前往您的机器人或频道的“余额”或“变现”部分，然后点击“购买广告”。
点击该按钮后，将调用`payments.getStarsRevenueAdsAccountUrl` 函数（需传入机器人/频道地址peer）。
返回的 URLurl将引导用户进入一个页面，用户可以在该页面上为传入的频道/机器人投放广告peer。

广告支付交易类型为starsTransactionPeerAds。

将星星从企业帐户转移到企业机器人 

inputInvoiceBusinessBotTransferStars#f4997e42 bot:InputUser stars:long = InputInvoice;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;---functions---payments.getStarsStatus#4ea9b3bf flags:# ton:flags.0?true peer:InputPeer = payments.StarsStatus;

inputInvoiceBusinessBotTransferStars可用于将星星从连接到企业机器人的用户帐户余额转移到企业机器人的余额。

可以通过业务 连接调用payments.getStarsStatus并使用 peer=inputPeerSelf获取用户余额中的可用星星数量。

要转移星星，请使用inputInvoiceBusinessBotTransferStars(with=inputPeerSelf ) 调用payments.getPaymentForm，并按照通常的支付流程 »，所有方法调用均通过业务连接执行。bot

我的明星深度链接

我的 Stars 深度链接 »和我的 Toncoin 深度链接 »可以将用户带到我的 Stars/我的 Toncoin 页面，其中包含充值按钮、Star/TON 交易历史记录、统计数据以及更多内容，如上文所述。

吨币 

starsTonAmount#74aee3e0 amount:long = StarsAmount;messageActionGiftTon#a8a3c699 flags:# currency:string amount:long crypto_currency:string crypto_amount:long transaction_id:flags.0?string = MessageAction;inputStickerSetTonGifts#1cf671a0 = InputStickerSet;

在 API 的某些地方，可以使用 toncoin 代替 Stars：在这种情况下，将使用starsTonAmount构造函数代替starsAmount，以加密货币的最小单位（目前为纳吨，1/1_000_000_000即 toncoin 的十亿分之一）指定 TON 的数量。

当 TON 被赠送给用户时，会收到messageActionGiftTon：此构造函数及其内容应显示在inputStickerSetTonGifts » stickerset »中相应贴纸的旁边：