Telegram 机器人与 Stars：付费操作实战手册
如果一位创作者已经拥有 Telegram 受众，机器人就能把这群受众变成付费操作：一份报告、一个文件、一个积分包、一条私有命令、一个小型服务，或一次与媒体相关的解锁。
尴尬之处不在于按钮，而在于交接。买家需要足够的 Stars，机器人需要一张干净的账单，而付费操作只应在 Telegram 确认付款之后才解锁。
这本手册面向计划用 Telegram Stars 做机器人交付付费操作的创作者与运营者。如果你的读者对余额本身还很陌生，请先从什么是 Telegram Stars开始。如果买家在上线前需要 Stars，请在机器人提示上线之前引导他们去充值 Telegram Stars。
快速答案
当你把报价保持得小而可验证时，Telegram 机器人付费操作的效果最好。
请使用这个流程：
- 定义一项付费操作。
- 向买家展示他们将获得什么。
- 为这项操作发送一张 Stars 账单。
- 在接受付款前检查 pre-checkout 请求。
- 只在成功支付事件之后交付。
- 保存付款引用，让支持与退款不再靠猜。
- 告诉买家如何在解锁时刻之前获得 Stars。
Telegram 的 Stars 支付文档描述了数字商品与服务的基本账单顺序：sendInvoice、pre_checkout_query、answerPreCheckoutQuery、successful_payment，然后交付。Bot API 在这些付款中使用 XTR 作为 Stars 货币标签。
这是技术骨架。创作者的工作更简单：把付费操作讲得足够清楚，让买家知道自己为什么要花 Stars。
这本手册涵盖什么
请把这本手册用于机器人交付的付费操作，例如：
- 解锁一个可下载文件；
- 生成一份私有报告；
- 向机器人账户添加积分；
- 开启一条付费命令；
- 交付定制的清单、提示词包、图表或模板；
- 提供一次由机器人处理的一次性服务。
不要把这些和所有 Telegram Stars 流程混为一谈。
付费媒体用于付费的照片、视频和受支持的媒体解锁。如果你的产品是一次媒体投放，请阅读 Telegram 付费媒体买家指南，以及关于如何为 Telegram 付费媒体用 Stars 定价的指南。
Star 订阅通过带月费的付费邀请链接来限制对频道的访问。小程序也可以使用 Stars，但买家流程不同。如果是这种情况，请使用关于如何用 Stars 为 Telegram 小程序付款的指南。
如果你需要先看更宏观的全貌，请从如何用 Stars 变现 Telegram 内容开始。
第 1 步：定义付费操作
不要从账单开始，要从买家得到的东西开始。
无力的付费操作承诺听起来是这样的：
- “高级访问。”
- “解锁更多。”
- “支持机器人。”
- “获取额外内容。”
这些说法会带来支持问题，因为买家说不清付款后到底有什么改变。
更有力的付费操作承诺是具体的：
- “生成一份私有审计报告。”
- “解锁完整的 PDF 模板包。”
- “向你的机器人余额添加 50 个积分。”
- “运行一次高级图表命令。”
- “打开这节课的私有清单。”
在为任何东西定价之前，先写一句话：
付款之后，买家得到 ________。
如果这句话含糊，机器人流程也会显得含糊。
第 2 步：发送 Stars 账单
对于标准的机器人账单，Telegram 的 Bot API 方法是 sendInvoice。对于 Stars 付款，账单使用 Stars 货币标签 XTR。
一份实用的账单清单：
- 把
currency设为XTR； - 在 Telegram 文档允许的地方，为 Stars 付款保持提供商令牌为空；
- 为一次 Stars 付款使用单个价格项；
- 把你的内部订单引用放进 payload；
- 让标题和描述足够简短，便于买家辨认该操作；
- 不要把同一个 payload 复用于不相关的操作。
payload 很重要，因为支付界面并不是你的整个订单系统。你的机器人仍然需要知道这张账单属于哪个用户、哪项操作和什么价格。
良好的内部 payload 数据通常包括：
- 买家用户 ID；
- 付费操作 ID；
- 预期的 Stars 金额；
- 订单时间戳；
- nonce 或唯一订单 ID；
- 诸如
created、pending、paid、delivered或refunded的状态。
让公开的账单文案保持人性化。买家不应看到内部 ID 或开发者用语。
糟糕的账单标题：
SKU_XTR_CMD_ADV_2026
更好的账单标题：
高级图表报告
糟糕的账单描述：
在回调校验后执行付费操作。
更好的账单描述：
解锁这个机器人的一份私有图表报告。
第 3 步：把 pre-checkout 当作护栏
Telegram 会在付款完成之前发送一个 pre-checkout 查询。请把它当作最后的安全检查，而不是一道形式。
在批准之前，请确认：
- 用户仍与订单匹配；
- 付费操作仍然存在；
- 预期的 Stars 金额仍然一致；
- 该操作仍然可用；
- 订单尚未被支付或取消；
- payload 尚未过期。
如果有任何不匹配，请用清晰的错误信息拒绝这个 pre-checkout 查询。不要让一张过期账单解锁错误的操作。
对于销售限量物品、限时访问或生成式输出的机器人，这一点尤其重要。用户可能会在报价更改之后点击一个旧的账单链接。你的机器人应该知道该怎么做。
第 4 步：只在成功之后交付
点击按钮不是付款。pre-checkout 通过不是交付。请在 Telegram 发送成功支付事件之后再交付。
一个干净的交付流程是这样的：
- 接收
successful_payment。 - 把它匹配到内部订单。
- 保存 Telegram 支付扣款 ID。
- 把订单标记为已付款。
- 交付付费操作。
- 把订单标记为已交付。
- 向买家发送一条简短的确认信息。
如果付费操作是即时的，例如一个文件或积分包，交付可以在确认后立即进行。如果它需要处理，请告诉买家正在发生什么以及接下来该期待什么。
让支持保持务实。如果你保存了订单 ID、付费操作、Stars 金额、支付扣款 ID 和交付状态，你就能回答大多数支持问题，而无需翻查聊天记录。
第 5 步：让买家充值时机一目了然
买家这一侧很容易被忽略。创作者通常在自己已经有 Stars 时测试机器人。而真实买家可能带着空余额到来。
Telegram 的 Stars 支付文档说，用户在为数字商品和服务付款之前，可在必要时获取 Stars。这并不意味着对每位买家来说这一额外步骤都毫无摩擦。如果你的付费操作在某个特定时间上线，请尽早提醒受众。
一条简单的上线信息可以这样说：
机器人将用 Telegram Stars 解锁这份付费报告。如果你还没有足够的 Stars，请在上线前充值，以免在结账时手忙脚乱。
这正是 MyStars 自然契合之处。创作者无需为付费操作本身把买家带离 Telegram。他们只需要买家在解锁时刻之前备好 Stars。请在投放之前就引导买家去充值 Telegram Stars，而不是等他们已经心生不满之后。
如果你也做付费媒体投放，请使用付费媒体上线计划来安排预告、买家提醒以及上线后的衡量。
决策分支
如果付费价值是一个文件或模板
请把付款保持为一次性。在成功付款后交付文件，然后发送一条简短的收据式信息。
不要让买家手动去找管理员要文件。那会把机器人流程变成一条支持队列。
如果付费价值是一份生成的报告
请告诉买家报告是即时的还是排队的。
如果生成可能失败，请把付款确认与交付状态分开：
已付款，生成中；已付款，已交付；已付款，失败 - 需要支持。
这会让退款和支持更轻松。
如果付费价值是积分
请只在成功付款后添加积分，并立即显示新余额。
如果积分会过期，请在结账前说明。隐藏的过期规则会引发投诉。
如果付费价值是媒体
请使用正确的流程。机器人账单可以销售数字商品或服务，但付费媒体有其自身的 Bot API 方法和产品行为。如果你在销售一次照片/视频/媒体解锁，请在动手之前把流程与 Telegram 付费媒体买家指南做对比。
如果付费价值是频道访问
那可能是一次 Star 订阅或另一种访问流程，而不是一次性的机器人操作。请在文案中把月度访问、一次性付费操作和付费媒体分开。
应当避免的错误
- 销售含糊的
高级承诺却不说明解锁什么。 - 把点击按钮当作付款。
- 在 pre-checkout 之后交付，而不是在成功付款之后。
- 忘记保存 Telegram 支付扣款 ID。
- 把一种 payload 格式复用于不相关的操作。
- 让旧的账单链接解锁已更改的报价。
- 把过期或使用限制隐藏到付款之后。
- 在面向买家的账单文案中使用开发者标签。
- 只在上线已经开始之后才引导买家去充值。
- 把每一种 Stars 流程都叫做
付费帖子，这会混淆付费媒体、订阅、机器人账单和纯文本频道内容。
故障排查
买家说他付款了，但机器人没有解锁
可能的原因：
- 机器人没有接收或处理
successful_payment； - 内部订单 ID 与 payload 不匹配；
- 付款后交付失败；
- 机器人把订单标记为已付款，却没有标记为已交付。
修复：
- 按用户 ID 和订单 ID 搜索；
- 检查保存的支付扣款 ID；
- 核实付费操作状态；
- 如果付款成功且物品有效，则手动交付；
- 记录这次失败，让同一个 bug 不再重演。
买家因为没有 Stars 而无法付款
可能的原因：
- 买家到了付款时刻，却没有备好足够的 Stars。
修复：
- 添加一条上线前提醒；
- 在上线说明中加入一个
充值 Telegram Stars链接； - 让机器人的付款信息简短清晰；
- 不要把充值指引埋进一长段公告里。
pre-checkout 失败
可能的原因：
- 订单已过期；
- payload 格式有误；
- 预期金额已更改；
- 付费操作不再可用；
- 机器人已经处理过该订单。
修复：
- 返回一条清晰的错误信息；
- 让用户创建一张新账单；
- 避免不作解释地静默失败。
收到退款或支持请求
可能的原因：
- 买家为错误的操作付了款；
- 交付失败；
- 报价文案不清晰；
- 买家本以为是订阅或媒体解锁，却买了一项机器人操作。
修复：
- 检查支付扣款 ID 和交付日志；
- 根据你的政策和 Telegram 可用的方法，判断退款是否合适；
- 如果多名买家都误解了同一点，请重写报价。
常见问题
Telegram 机器人可以用 Stars 收取付费操作的费用吗？
可以，Telegram 的 Stars 支付文档涵盖通过机器人和小程序销售的数字商品与服务。对于机器人账单，关键部分是 Stars 货币标签 XTR、pre-checkout 处理、成功支付确认，以及付款后的交付。
XTR 是什么意思？
XTR 是 Telegram 在 Bot API 支付流程中用于 Stars 的货币标签。请在 Stars 账单中使用它，而不要把 Stars 当成普通的法币货币代码。
Stars 账单需要支付提供商令牌吗？
Telegram 的 Bot API 文档指出，在出现该参数的 Telegram Stars 付款中，应传入一个空的提供商令牌。由于 API 细节可能变化，请在实现前查阅当前的 Bot API 文档。
机器人应该在什么时候交付该操作？
在成功支付事件之后，而不是在用户点击付款按钮之后，也不仅仅是在 pre-checkout 通过之后。
如果买家没有足够的 Stars 怎么办？
请在上线前提醒买家。他们可以先准备好余额，然后在机器人账单出现时于 Telegram 内解锁。如果他们需要更多 Stars，请引导他们去充值 Telegram Stars。
机器人付费操作和付费媒体是一回事吗？
不是。付费媒体用于付费的照片、视频和受支持的媒体解锁。机器人付费操作可以是一个文件、报告、积分包、命令或由机器人交付的服务。请把流程和文案分开。
Stars 付款可以退款吗？
Telegram 的 Bot API 包含用于成功 Stars 付款的 refundStarPayment。请保存支付扣款 ID 和你的内部订单状态，以便清晰地处理支持与退款决定。
来源与佐证
- Telegram Stars 发布：Telegram Stars: Pay for Digital Goods and More。
- 面向机器人的 Stars 支付流程：Telegram Stars Payments。
- 机器人账单参数：Bot API sendInvoice。
- 付费媒体范围：Bot API sendPaidMedia。
- Star 订阅与付费媒体公告：Telegram Super Channels, Star Reactions and Subscriptions。
- Stars 条款与余额范围：Telegram Stars Terms。
最终清单
在你上线一项机器人付费操作之前：
- 付费操作是具体的；
- 账单标题对人类可读；
- payload 映射到单个内部订单；
- Stars 金额在付款前已检查；
- 交付发生在成功付款之后；
- 支持可以找到扣款 ID 和交付状态；
- 买家知道如何在机器人提示之前充值 Stars。