# Рецепт: Telegram-бот

> Продавайте команди бота, роль чи приватну групу. Кожен користувач отримує власний рахунок; підписаний вебхук відкриває доступ.

Бот грошей не бачить. На `/buy` він надсилає користувачеві його власне посилання на рахунок; ваш сервер чує `invoice.fulfilled` і відкриває доступ. Кожна платна команда питає Perly Pay, тож після перезапуску нічого не губиться. Discord — так само, через роль.

> **Примітка:** З асистентом: цей рецепт робить у вашому проєкті скіл `sell-bot-access` плагіна Perly Pay для Claude Code — плагін і його приклад `examples/telegram-bot` (MIT) уже на шляху. Доти будь-який асистент прочитає той самий скіл з `/.well-known/skills/perly-pay-sell-bot-access/SKILL.md`.

## Як це працює

1. **Продукт і ціна** — Разова або довічна — «назавжди», строкова — для перепусток, підписка — для членства з поновленням рахунком.
2. **Клієнт на кожного користувача чату** — `external_id: "tg:<user id>"`. Пошту питайте лише для підписок: туди йдуть поновлення.
3. **/buy** — Рахунок з ідентифікатором чату в `metadata`, надісланий кнопкою. Один рахунок на користувача на день — завдяки ключу ідемпотентності.
4. **Відкрийте доступ** — За `invoice.fulfilled` візьміть ідентифікатор чату з `metadata` і відповідайте: повідомлення, одноразове запрошення, роль.
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. **Встановіть** — `npm install` у `examples/telegram-bot` (Node 20.12+).
2. **Ключ** — Скопіюйте `.env.example` у `.env` і впишіть тестовий ключ (`sk_test_…`) у `PERLY_PAY_SECRET_KEY`.
3. **Підготуйте** — `npm run setup` створює продукт і ціну вашим ключем та друкує їхні ідентифікатори для `.env`.
4. **Запустіть** — `npm start` (або `npm run dev`), як каже його README.
5. **Сплатіть без гаманця** — Напишіть боту `/buy`, відкрийте Pay і натисніть **Simulate payment**: бот скаже «Payment confirmed», а `/secret` відповість.

## Пастки

- Одне спільне платіжне посилання на всіх: не видно, хто сплатив. Рахунок на кожного, з ідентифікатором чату.
- Відкривати доступ, коли користувач натиснув «Я сплатив». Відкриває лише вебхук або `entitlements.check`.
- Доступ у пам'яті бота. Після перезапуску його немає; питайте Perly Pay.