# 配方：Telegram 机器人

> 出售机器人命令、角色或私密群组。每个用户都有自己的账单；签名 Webhook 开通访问。

机器人看不到钱。收到 `/buy` 时，它把用户专属的账单链接发给该用户；你的服务器收到 `invoice.fulfilled` 后开通访问。每个付费命令都询问 Perly Pay，所以重启后什么都不会丢。Discord 也一样，通过角色实现。

> **注意:** 配合助手：Perly Pay 插件的 `sell-bot-access` 技能会在你的项目中实现这个配方。可运行的示例是插件仓库中的 `examples/telegram-bot`（MIT）。

## 如何运作

1. **商品和价格** — 一次性或终身 — 用于“永久”，限期 — 用于通行证，订阅 — 用于按账单续订的会员。
2. **每个聊天用户一个客户** — `external_id: "tg:<user id>"`。只有订阅才需要询问邮箱：续订账单会发到那里。
3. **/buy** — 一张在 `metadata` 中带聊天 ID 的账单，通过按钮发送。借助幂等键，每个用户每天一张账单。
4. **开通访问** — 收到 `invoice.fulfilled` 时，从 `metadata` 取出聊天 ID 并回复：消息、一次性邀请、角色。
5. **付费命令** — `entitlements.check({ customer_external_id: "tg:<id>", product })`。

**/buy**

```js
const invoice = await pay.invoices.create(
  { line_items: [{ price: PRICE }], customer: customer.id, metadata: { chat_id: String(chatId) } },
  { idempotencyKey: `buy-${userId}-${today}` },
);
await tg("sendMessage", { chat_id: chatId, text: "Pay:", reply_markup: { inline_keyboard: [[{ text: "Pay", url: invoice.url }]] } });
```

## 运行示例

1. **安装** — 在 `examples/telegram-bot` 中运行 `npm install`（Node 20.12+）。
2. **密钥** — 把 `.env.example` 复制为 `.env`，在 `PERLY_PAY_SECRET_KEY` 中填入测试密钥（`sk_test_…`）。
3. **准备** — `npm run setup` 用你的密钥创建商品和价格，并打印它们的 ID 供 `.env` 使用。
4. **启动** — 按其 README 运行 `npm start`（或 `npm run dev`）。
5. **无需钱包即可付款** — 给机器人发 `/buy`，打开 Pay 并点 **Simulate payment**：机器人会回复“Payment confirmed”，`/secret` 也会有回应。

## 陷阱

- 所有人共用一个付款链接：看不出是谁付的。每人一张账单，带上聊天 ID。
- 用户点了“我已付款”就开通访问。只有 Webhook 或 `entitlements.check` 才能开通。
- 访问权限存在机器人内存里。重启后就没了；请询问 Perly Pay。