Боты Telegram и Stars: руководство по платным действиям

Если у автора уже есть аудитория в Telegram, бот может превратить эту аудиторию в платные действия: отчёт, файл, пакет кредитов, приватную команду, мини-сервис или разблокировку, связанную с медиа.

Неудобная часть — не кнопка. Это передача. Покупателю нужно достаточно Stars, боту нужен аккуратный счёт, а платное действие должно разблокироваться только после того, как Telegram подтвердит оплату.

Это руководство для авторов и операторов, которые планируют платное действие, выдаваемое ботом через Telegram Stars. Если ваши читатели ещё новички в самом балансе, начните с что такое Telegram Stars. Если покупателям нужны Stars до запуска, отправьте их пополнить Telegram Stars до того, как появится запрос бота.

Короткий ответ

Платное действие бота Telegram работает лучше всего, когда предложение остаётся небольшим и проверяемым.

Используйте такой поток:

1. Определите одно платное действие.
2. Покажите покупателю, что он получит.
3. Отправьте счёт в Stars за это действие.
4. Проверьте запрос pre-checkout до приёма оплаты.
5. Выдавайте только после события успешной оплаты.
6. Сохраните ссылку на платёж, чтобы поддержка и возвраты не были гаданием.
7. Расскажите покупателям, как получить Stars до момента разблокировки.

Документация Telegram по оплате Stars описывает базовую последовательность счёта для цифровых товаров и услуг: sendInvoice, pre_checkout_query, answerPreCheckoutQuery, successful_payment, затем выдача. Bot API использует XTR как тег валюты Stars для этих платежей.

Это технический каркас. Задача автора проще: сделать платное действие достаточно понятным, чтобы покупатель знал, за что тратит Stars.

Что охватывает это руководство

Используйте это руководство для платных действий, выдаваемых ботом, таких как:

• разблокировка скачиваемого файла;
• генерация приватного отчёта;
• добавление кредитов на аккаунт бота;
• открытие платной команды;
• выдача индивидуального чек-листа, набора промптов, графика или шаблона;
• предоставление доступа к разовой услуге, которую обрабатывает бот.

Не смешивайте это с любым потоком Telegram Stars.

Платные медиа — это платные фото, видео и поддерживаемые медиа-разблокировки. Если ваш продукт — это медиа-дроп, прочитайте руководство покупателя по платным медиа Telegram и руководство о том, как назначать цену платным медиа Telegram в Stars.

Подписки Star ограничивают доступ к каналу через платную пригласительную ссылку с ежемесячной платой. Мини-приложения тоже могут использовать Stars, но поток покупателя отличается. Если это ваш случай, используйте руководство о том, как оплачивать мини-приложения Telegram через Stars.

Если сначала нужна более широкая картина, начните с того, как монетизировать контент Telegram через Stars.

Шаг 1: определите платное действие

Не начинайте со счёта. Начните с того, что получает покупатель.

Слабые обещания платного действия звучат так:

• «Премиум-доступ.»
• «Разблокируй больше.»
• «Поддержи бота.»
• «Получи дополнительный контент.»

Эти фразы порождают вопросы в поддержку, потому что покупатель не понимает, что меняется после оплаты.

Более сильное обещание платного действия — конкретное:

• «Сгенерировать один приватный аудит-отчёт.»
• «Разблокировать полный набор PDF-шаблонов.»
• «Добавить 50 кредитов на баланс бота.»
• «Один раз запустить расширенную команду графиков.»
• «Открыть приватный чек-лист для этого урока.»

Прежде чем назначать цену, напишите одно предложение:

После оплаты покупатель получает ________.

Если предложение расплывчатое, поток бота тоже будет расплывчатым.

Шаг 2: отправьте счёт в Stars

Для стандартного счёта бота метод Bot API Telegram — sendInvoice. Для платежей в Stars счёт использует тег валюты XTR.

Практичный чек-лист для счёта:

• укажите currency как XTR;
• оставляйте токен провайдера пустым для платежей в Stars там, где это разрешает документация Telegram;
• используйте одну ценовую позицию для платежа в Stars;
• поместите свою внутреннюю ссылку на заказ в payload;
• держите заголовок и описание достаточно короткими, чтобы покупатель узнал действие;
• не используйте один и тот же payload для не связанных действий.

Payload важен, потому что экран оплаты — это не вся ваша система заказов. Боту всё ещё нужно знать, какому пользователю, действию и цене соответствует этот счёт.

Хорошие данные внутреннего payload обычно включают:

• ID пользователя-покупателя;
• ID платного действия;
• ожидаемую сумму Stars;
• метку времени заказа;
• nonce или уникальный ID заказа;
• статус, такой как created, pending, paid, delivered или refunded.

Держите публичный текст счёта человечным. Покупатель не должен видеть внутренние ID или формулировки разработчика.

Плохой заголовок счёта:

SKU_XTR_CMD_ADV_2026

Лучше заголовок счёта:

Расширенный отчёт по графику

Плохое описание счёта:

Выполнить платное действие после проверки callback.

Лучше описание счёта:

Разблокируйте один приватный отчёт по графику от этого бота.

Шаг 3: относитесь к pre-checkout как к страховочному барьеру

Telegram отправляет запрос pre-checkout до завершения платежа. Относитесь к этому как к финальной проверке безопасности, а не как к формальности.

Перед одобрением убедитесь, что:

• пользователь всё ещё соответствует заказу;
• платное действие всё ещё существует;
• ожидаемая сумма Stars всё ещё совпадает;
• действие всё ещё доступно;
• заказ ещё не оплачен и не отменён;
• payload не истёк.

Если что-то не совпадает, отклоните запрос pre-checkout с понятным сообщением об ошибке. Не позволяйте устаревшему счёту разблокировать неверное действие.

Это особенно важно для ботов, продающих ограниченные товары, доступ по времени или сгенерированные результаты. Пользователь может нажать старую ссылку счёта после того, как предложение изменилось. Бот должен знать, что делать.

Шаг 4: выдавайте только после успеха

Нажатие кнопки — это не оплата. Одобрение pre-checkout — это не выдача. Выдавайте после того, как Telegram отправит событие успешной оплаты.

Чистый поток выдачи выглядит так:

1. Получите successful_payment.
2. Сопоставьте его с внутренним заказом.
3. Сохраните ID платёжного списания Telegram.
4. Отметьте заказ как оплаченный.
5. Выдайте платное действие.
6. Отметьте заказ как выданный.
7. Отправьте покупателю короткое подтверждение.

Если платное действие мгновенное, например файл или пакет кредитов, выдача может произойти сразу после подтверждения. Если оно требует обработки, расскажите покупателю, что происходит и чего ждать дальше.

Держите поддержку практичной. Если вы сохраняете ID заказа, платное действие, сумму Stars, ID платёжного списания и статус выдачи, вы сможете ответить на большинство вопросов поддержки, не копаясь в истории чата.

Шаг 5: сделайте очевидным время пополнения у покупателя

О стороне покупателя легко забыть. Авторы обычно тестируют бота, когда у них уже есть Stars. Реальные покупатели могут прийти с пустым балансом.

Документация Telegram по оплате Stars говорит, что пользователи могут при необходимости приобрести Stars до оплаты цифровых товаров и услуг. Это не значит, что дополнительный шаг беспроблемен для каждого покупателя. Если ваше платное действие запускается в определённое время, предупредите аудиторию заранее.

Простое сообщение о запуске может звучать так:

Бот разблокирует платный отчёт с помощью Telegram Stars. Если у вас ещё недостаточно Stars, пополните до запуска, чтобы не делать это во время оплаты.

Вот где MyStars вписывается естественно. Автору не нужно выводить покупателя из Telegram ради самого платного действия. Им нужно лишь, чтобы у покупателей были Stars наготове до момента разблокировки. Отправляйте покупателей пополнить Telegram Stars до дропа, а не после того, как они уже раздражены.

Если вы также запускаете дропы платных медиа, используйте план запуска платных медиа для планирования тизеров, напоминаний покупателю и измерений после запуска.

Ветви решений

Если платная ценность — это файл или шаблон

Сделайте оплату разовой. Выдайте файл после успешной оплаты, затем отправьте короткое сообщение в стиле чека.

Не заставляйте покупателя вручную просить файл у администратора. Это превращает поток бота в очередь поддержки.

Если платная ценность — это сгенерированный отчёт

Расскажите покупателю, мгновенный отчёт или в очереди.

Если генерация может сбоить, отделите подтверждение оплаты от статуса выдачи:

• оплачено, генерируется;
• оплачено, выдано;
• оплачено, сбой - нужна поддержка.

Это упрощает возвраты и поддержку.

Если платная ценность — это кредиты

Добавляйте кредиты только после успешной оплаты. Сразу показывайте новый баланс.

Если кредиты сгорают, скажите об этом до оплаты. Скрытые правила сгорания вызывают жалобы.

Если платная ценность — это медиа

Используйте правильный поток. Счёт бота может продавать цифровой товар или услугу, но у платных медиа есть свой метод Bot API и поведение продукта. Если вы продаёте разблокировку фото/видео/медиа, сравните поток с руководством покупателя по платным медиа Telegram перед сборкой.

Если платная ценность — это доступ к каналу

Это может быть подписка Star или другой поток доступа, а не разовое действие бота. Держите в текстах раздельно ежемесячный доступ, разовые платные действия и платные медиа.

Ошибки, которых стоит избегать

• Продавать расплывчатое обещание премиум без указания, что разблокируется.
• Считать нажатие кнопки оплатой.
• Выдавать после pre-checkout, а не после успешной оплаты.
• Забывать сохранять ID платёжного списания Telegram.
• Повторно использовать один формат payload для не связанных действий.
• Позволять старым ссылкам счетов разблокировать изменившиеся предложения.
• Скрывать сгорание или лимиты использования до оплаты.
• Использовать метки разработчика в тексте счёта, который видит покупатель.
• Отправлять покупателей пополнять баланс только после того, как запуск уже начался.
• Называть любой поток Stars платными постами, что может путать платные медиа, подписки, счета ботов и текстовый контент канала.

Устранение неполадок

Покупатель говорит, что заплатил, но бот не разблокировал

Вероятные причины:

• бот не получил или не обработал successful_payment;
• внутренний ID заказа не совпал с payload;
• выдача сбойнула после оплаты;
• бот отметил заказ оплаченным, но не выданным.

Решение:

• ищите по ID пользователя и ID заказа;
• проверьте сохранённый ID платёжного списания;
• проверьте статус платного действия;
• выдайте вручную, если оплата прошла и товар валиден;
• залогируйте сбой, чтобы тот же баг не повторился.

Покупатель не может заплатить, потому что у него нет Stars

Вероятная причина:

• покупатель дошёл до момента оплаты без достаточного количества Stars наготове.

Решение:

• добавьте напоминание перед запуском;
• включите ссылку пополнить Telegram Stars в инструкции к запуску;
• держите платёжное сообщение бота коротким и понятным;
• не закапывайте инструкцию по пополнению внутри длинного анонса.

Pre-checkout сбоит

Вероятные причины:

• заказ истёк;
• payload некорректен;
• ожидаемая сумма изменилась;
• платное действие больше недоступно;
• бот уже обработал заказ.

Решение:

• верните понятное сообщение об ошибке;
• дайте пользователю создать новый счёт;
• избегайте тихого сбоя без объяснения.

Поступает запрос на возврат или поддержку

Вероятные причины:

• покупатель заплатил за неверное действие;
• выдача сбойнула;
• текст предложения был непонятным;
• покупатель ожидал подписку или разблокировку медиа, но купил действие бота.

Решение:

• проверьте ID платёжного списания и журнал выдачи;
• решите, уместен ли возврат по вашей политике и доступным методам Telegram;
• перепишите предложение, если несколько покупателей неправильно понимают один и тот же момент.

Частые вопросы

Может ли бот Telegram принимать Stars за платное действие?

Да, документация Telegram по оплате Stars охватывает цифровые товары и услуги, продаваемые через ботов и мини-приложения. Для счёта бота важны тег валюты XTR, обработка pre-checkout, подтверждение успешной оплаты и выдача после оплаты.

Что означает XTR?

XTR — это тег валюты, который Telegram использует для Stars в платёжном потоке Bot API. Применяйте его для счетов в Stars, а не относитесь к Stars как к обычному коду фиатной валюты.

Нужен ли счетам в Stars токен платёжного провайдера?

В документации Bot API сказано передавать пустой токен провайдера для платежей в Telegram Stars там, где этот параметр присутствует. Проверьте актуальную документацию Bot API перед реализацией, так как детали API могут меняться.

Когда бот должен выдавать действие?

После события успешной оплаты, а не после того, как пользователь нажал кнопку оплаты, и не только после одобрения pre-checkout.

Что если у покупателя недостаточно Stars?

Предупредите покупателей до запуска. Они могут заранее подготовить баланс, а затем разблокировать действие внутри Telegram, когда появится счёт бота. Если нужно больше Stars, отправьте их пополнить Telegram Stars.

Платное действие бота — это то же, что платные медиа?

Нет. Платные медиа — это платные фото, видео и поддерживаемые медиа-разблокировки. Платное действие бота может быть файлом, отчётом, пакетом кредитов, командой или услугой, которую выдаёт бот. Держите поток и тексты раздельно.

Можно ли вернуть платежи в Stars?

В Bot API Telegram есть refundStarPayment для успешных платежей в Stars. Сохраняйте 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 до запроса бота.