Telegram Stars: подключение, товары и подписки

Telegram Stars (звёзды) — внутренняя валюта Telegram. Подключение Stars в Botman позволяет продавать товары и подписки прямо в Telegram-боте: покупатель платит звёздами, не выходя из чата.

Главное отличие от других платёжных провайдеров: не нужны ни ключи, ни договор с банком, ни онлайн-касса. Вы просто выбираете своего Telegram-бота, который уже подключён к Botman, — и всё. Выручка в звёздах копится на балансе этого бота в Telegram.

Как всё связано. Подключение Stars → товар (разовая оплата) или тарифный план (подписка) → блок «Товар» или «Подписка» в сценарии бота. Одно подключение можно использовать в нескольких товарах и тарифных планах.

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

Кому не подходит:

• Физические товары и офлайн-услуги (доставка, вещи, запись в салон). По правилам Telegram звёзды — только для цифрового. Для физического подключайте ЮKassa, Т-Банк, Точку и других провайдеров.

• Продажи не в Telegram (MAX, VK, веб-чат и т. д.) — звёзды работают только в Telegram.

• Подписка с периодом неделя, календарный месяц или год — Stars умеет только ровно 30 дней.

И обратное правило: если вы продаёте цифровой товар внутри Telegram, Telegram требует принимать оплату именно звёздами. Так он соблюдает правила App Store и Google Play.

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

Что нужно до начала¶

Проверьте четыре пункта — без них подключение не сохранится или не будет работать.

• Telegram-бот уже подключён к Botman как Telegram-канал. Это должен быть ваш собственный боевой бот. Тестовые каналы в список выбора не попадают.

• Вебхук бота смотрит на Botman. Если бот подключён к другому сервису, Botman не сможет принимать платежи и выдаст ошибку «Сначала подключите Telegram-бота к Botman».

• Вы решили, какой бот будет принимать деньги. Выбор бота в подключении нельзя поменять никогда — только создать новое подключение. Выручка копится на балансе именно этого бота.

• Вы работаете в новом интерфейсе кабинета. Настройки Stars доступны только в нём.

Что НЕ нужно (в отличие от ЮKassa, Т-Банка, Точки и других):

• ключи API и платёжный токен — у Stars их нет;

• договор с банком и эквайринг;

• онлайн-касса;

• настройки в BotFather — Botman сам дописывает боту приём событий оплаты при сохранении подключения.

Совет. Перед запуском продаж на основном боте прогоните полный цикл на отдельном «тренировочном» боте: оплата, продление, отмена. Живые списания и возвраты перед релизом не проверялись. Учтите, что тренировочный бот тоже должен быть подключён как обычный (не тестовый) Telegram-канал.

Шаг за шагом: подключаем Stars¶

Вся форма подключения помещается на один экран: в ней всего два поля. Занимает минуту.

1️⃣ Откройте раздел платёжных провайдеров. В кабинете: Интеграции → «Платежные провайдеры».
2️⃣ Нажмите «Новое подключение» и выберите в списке «Telegram Stars».
3️⃣ Заполните «Название подключения». Это название видите только вы. Пишите так, чтобы потом не перепутать: например, «Stars — бот Школа йоги».
4️⃣ Выберите «Telegram-бот».В поле с подсказкой «Выберите подключённого бота» откроется список ваших боевых Telegram-ботов.

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

• ☝️Внимание: после сохранения поле блокируется навсегда. Ошиблись ботом — создавайте новое подключение.

5️⃣ Нажмите «Сохранить». Botman сам настроит бота на приём платёжных событий. В BotFather ничего делать не нужно.

Готово: подключение появится в списке платёжных провайдеров. Теперь на нём можно создавать товары и тарифные планы подписки.

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

Разовые товары¶

Разовый товар — покупка «один раз и навсегда»: гайд, урок, консультация, доступ к материалу. Покупатель платит звёздами один раз, сценарий бота идёт дальше.

Как создать товар¶

1️⃣ Откройте Интеграции → вкладка «Товары» → «Создать товар». Откроется окно «Новый товар».
2️⃣ Заполните поля:

• Подключение к провайдеру — выберите ваше подключение Telegram Stars. В списке оно подписано с пометкой «(Telegram Stars)».

• Название товара — обязательное, до 32 символов. Пишите коротко: Telegram покажет его в счёте.

• Описание — до 255 символов.

• Цена, Stars — только целое число звёзд. Верхнего потолка у разового товара нет.

3️⃣ Нажмите «Создать». Товар получит статус «Активен».
4️⃣ В конструкторе поставьте в сценарий блок «Товар» и выберите этот товар.

Настроек чеков (НДС, СНО, способ и предмет расчёта) в форме товара Stars нет: они есть только у провайдеров с онлайн-кассой🧾

Как проходит оплата глазами покупателя¶

1. Покупатель доходит в сценарии до блока «Товар».

2. Botman создаёт заказ и просит Telegram выставить счёт в звёздах.

3. В чате с ботом появляется счёт с кнопкой «Оплатить».

4. Покупатель нажимает «Оплатить». Telegram спрашивает Botman, актуален ли счёт.

5. Botman проверяет заказ и отвечает «ок».

6. Telegram списывает звёзды и сообщает Botman: оплачено.

7. Сценарий идёт дальше по выходу «успешная оплата».

Доступ выдаётся только после успешной оплаты, не раньше.

Сколько живёт счёт¶

Заказ на разовый товар действует 24 часа. Если покупатель вернулся позже и нажал «Оплатить» в старом счёте, Telegram покажет: «Счёт недоступен. Откройте новую ссылку на оплату в боте.» Покупателю нужно снова пройти до блока «Товар» — бот выставит свежий счёт.

Подписки¶

Подписка на Stars продлевается каждые 30 дней, строго. Продлевает не Botman, а сам Telegram: он списывает звёзды у покупателя и сообщает Botman новую дату окончания доступа.

Именно поэтому в плане на Stars период подписан «Каждые 30 дней», а не «Ежемесячно»: 30 дней не равны календарному месяцу. Другие периоды (неделя, квартал, год) на Stars недоступны.

Как создать подписку¶

1️⃣ Откройте Интеграции → вкладка «Тарифные планы» → «Создать тарифный план».
2️⃣ Заполните поля:

• Подключение к провайдеру — ваше подключение Telegram Stars.

• Название плана — его видите и вы, и покупатель.

• Описание — коротко, что входит в подписку.

• «Цена, Stars» — целое число от 1 до 10 000 звёзд.

• Периодичность — у Stars стоит «Каждые 30 дней». Неделя, месяц, квартал и год, которые есть у других провайдеров, здесь недоступны.

3️⃣ Сохраните план.
4️⃣ В конструкторе поставьте блок «Подписка» и выберите этот план. Покупатель получит карточку оплаты прямо в чате.

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

Жизненный цикл подписки¶

Счёт на подписку не сгорает¶

В отличие от разового товара, у заказа на подписку нет срока жизни: ссылка на оплату остаётся рабочей, пока покупатель не заплатит.

Если у покупателя нет звёзд и другие ситуации¶

Нехватку звёзд Telegram решает сам, без участия Botman. Покупатель нажимает «Оплатить», Telegram предлагает пополнить баланс. Звёзды покупаются встроенной покупкой через App Store или Google Play, через бот @PremiumBot или через Fragment. Botman в покупке звёзд не участвует и никаких событий об этом не получает.

Заказ при этом уже создан, и дальше всё зависит от типа покупки:

Как вернуть звёзды покупателю¶

Споры и возвраты по покупкам — полностью ответственность продавца.

В интерфейсе Botman вернуть звёзды нельзя — ни продавцу, ни поддержке Botman. Кнопки возврата звёзд нет нигде.

Telegram возврат позволяет: у Bot API есть метод refundStarPayment. Продавец делает возврат сам, вне Botman, через своего бота в Telegram.

Что делает Botman при возврате. Telegram сообщает Botman, что платёж возвращён. Botman помечает заказ возвращённым, и по нему больше ничего не уходит в сценарий: доступ по этой оплате уже не выдаётся. Если доступ выдан раньше (ссылка, метка, добавление в канал), отозвать его продавцу нужно вручную.

Ошибки и что с ними делать¶

• Нет нужного бота в выпадающем списке. Бот подключён как тестовый канал или не подключён вовсе.

• Выбрали не того бота. Исправить нельзя — только новое подключение.

• Ищете период «Ежемесячно». Его нет: у Stars только «Каждые 30 дней».

• Сценарий никуда не ведёт после оплаты. Проверьте, что от выхода «успешная оплата» есть шаг выдачи доступа.

• Сценарий не публикуется, на блоке «Товар» или «Подписка» плашка о тарифе. Кабинет на тарифе, где платные блоки недоступны (например, Free). Нужен PRO, PREMIUM или UNLIMITED.

• Сценарий перестал принимать оплату. Скорее всего, товар отправлен в архив. Восстановите его в Интеграции → «Товары».

• Товара или плана нет в конструкторе. Он в архиве или его подключение неактивно.

• Поменяли цену плана, а подписчики платят по-старому. Так и задумано: цена фиксируется в момент оформления подписки.

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

Нужно ли что-то настраивать в BotFather? Нет. При сохранении подключения Botman сам дописывает боту приём событий оплаты.

Куда приходят деньги? Звёзды копятся на балансе того Telegram-бота, который выбран в подключении.

Можно ли поменять бота в подключении? Нет, никогда. Создайте новое подключение Stars с нужным ботом.

Можно ли сделать подписку на неделю или на год? Нет. Telegram продлевает подписку на звёзды только каждые 30 дней.

Почему период называется «Каждые 30 дней», а не «Ежемесячно»? Потому что это ровно 30 дней, а не календарный месяц. Например, оплата 1 марта продлится 31 марта, а не 1 апреля.

Покупатель отменил подписку — доступ пропадёт сразу? Нет. Доступ работает до конца уже оплаченных 30 дней. В Botman подписка будет с пометкой «Автопродление отключено».

Можно ли продавать звёздами в MAX или VK? Нет, только в Telegram.

Можно ли использовать тестовый канал для проверки? Нет, тестовые каналы в выборе не появляются. Для проверки подключите отдельного бота как обычный Telegram-канал.

Какая комиссия у Telegram и как вывести звёзды? Вывод — через платформу Fragment по правилам Telegram. Точную комиссию и курс смотрите в условиях Telegram для разработчиков ботов, в документации Botman их нет.

Можно ли продавать звёздами физические товары? Нет. Звёзды — только для цифровых товаров и услуг. Для доставки вещей или офлайн-услуг используйте других платёжных провайдеров.

Я на Free — могу продавать за звёзды? Настроить подключение, товары и собрать сценарий можно. Опубликовать сценарий с платным блоком — нет: для этого нужен PRO, PREMIUM или UNLIMITED.

Как автоматически закрыть доступ, когда подписка закончилась? Добавьте в стартовый блок сценария триггер «Изменение подписки» с событием «Завершена» и от него соберите шаги: убрать метку, отправить сообщение, предложить продлить.

У покупателя нет звёзд — что делать мне как продавцу? Ничего. Telegram сам предложит покупателю купить звёзды. Если он вернётся позже суток, для разового товара пусть пройдёт блок «Товар» заново.

Источники¶

• Как устроен раздел оплат и подписок в BotMan

• Товары

• Тарифные планы в BotMan

• «Звёзды» Telegram: оплата цифровых товаров и не только — блог Telegram

• Bot Payments API for Digital Goods and Services — инструкция Telegram для продавцов