Как я разработал подписочный сервис в Telegram

Настройка разбита на шаги. Пользователь приходит в бота по ссылке, в которой может быть реферальный код. Mini App предлагает выбрать тариф или пробный период, установить клиент, затем импортировать ссылку на подписку или отсканировать QR.

Сервис получает платформу из Telegram (Android, iOS, Windows или macOS). Показывает подходящую инструкцию и ссылку на рекомендованное клиентское приложение. Новому пользователю доступен бесплатный пробный период: 3 дня, один раз на человека. Если пробный период недоступен, приложение объясняет причину и предлагает тарифы.

Сообщение об успехе появляется после проверки подключения. Тем, кто начал настройку и остановился, сервис напоминает о следующем шаге.

Тарифы бывают месячные, квартальные и годовые, с уровнями Standard и Pro. У тарифа свой лимит устройств, а Pro поднимает его до 10 устройств. Дополнения, например выделенный IP, добавляются поверх тарифа.

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

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

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

Больше всего времени заняла надёжность платежей. Сервис принимает карты, мгновенные банковские платежи, внутреннюю валюту Telegram и криптовалюту. Есть оплата на веб-странице вне Telegram. Все способы создания платежа защищены устойчивой идемпотентностью запросов. Повтор с тем же ключом возвращает прежний результат без второго списания. Если запрос ещё выполняется, система сообщает об этом. Повторное использование ключа с другими данными отклоняется. Воркер с истёкшим правом обработки не может записать второе списание.

Платёжные провайдеры подключены к общему биллингу:

• один баланс на пользователя с журналом только на добавление: пополнение, списание за подписку, возврат, промокредит, реферальный кредит, корректировка, списание при выводе и исправление. Прежние денежные записи не редактируются;
• счета и списания с суммой к оплате и историей каждой попытки. Способ оплаты можно сохранить для следующих платежей;
• режимы продления: ручной, с приоритетом баланса, с приоритетом баланса и автопополнением, прямой автоплатёж. Отдельный сервис управляет повторными попытками и льготным периодом;
• самостоятельные возвраты с проверкой допустимости. В журнал добавляется обратная проводка, реферальное вознаграждение по возвращённому платежу отменяется;
• правила для ожидающих платежей: если платёж завис, интерфейс предлагает пользователю выбор действий.

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

Основной способ входа в Mini App использует Telegram. Также доступны Telegram OIDC, Google и другие OAuth-провайдеры, одноразовая ссылка (magic link) и привязка email. Если человек пришёл сначала через веб-оплату, затем через Telegram, его аккаунты автоматически связываются и объединяются. Подписка не разделяется между двумя записями.

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

В разделе «Доступ» пользователь один раз получает ссылку на подписку и QR. При необходимости сервис перевыпускает или меняет токен. Рядом с инструкциями находятся проверка подключения и шаги устранения неполадок. Пользователь может проверить устройство до обращения в поддержку.

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

Каждый пользователь получает 8-символьный реферальный код и ссылку. После первого платежа приглашённого его статус меняется с «ожидает» на «активен». Пригласившему начисляется доля каждого платежа: по умолчанию 20%, с индивидуальными ставками до 50% для VIP-партнёров. Новый приглашённый может получить небольшой бонус только на покупки, без возможности вывода. Вывод доступного баланса проходит через заявку, которую проверяет и исполняет оператор.

Отдельная партнёрская программа (affiliate) учитывает платных партнёров с двумя уровнями комиссии и собственными запросами на выплату.

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

Промокоды применяются на сервере. Код может быть процентом или фиксированной суммой, может действовать на один тариф и имеет лимиты использования и срока действия; для кампаний запуска есть автоприменение.

Подарки позволяют купить подписку для другого человека: получатель получает 12-символьный код со 180-дневным окном активации. Семейные тарифы и бизнес-места строятся на том же ядре, с B2B-кабинетом для управления местами. Уровни лояльности поощряют давних подписчиков.

Пользователь может обратиться к человеку или ИИ-агенту. Для агента заданы строгие ограничения.

Для ИИ-агента поддержки я написал цикл работы с OpenAI-совместимой моделью. Через инструменты он получает текущие данные аккаунта: подписку, устройства, серверные узлы, ссылку на подписку и тарифы. Для инструкций использует базу знаний. Его правила:

• факты об аккаунте берутся только из инструментов, никогда из памяти модели;
• инструкции по настройке берутся только из базы знаний;
• цены и состав тарифов запрашиваются при ответе;
• текст пользователя считается данными, а не инструкциями, поэтому сообщение «игнорируй свои правила» их не меняет;
• разрушительные действия двухфазные: агент показывает предварительный результат изменения, ждёт чёткого «да», потом применяет;
• когда затронуты деньги, безопасность аккаунта или рассерженный пользователь, он передаёт дело человеку, а не гадает;
• проверка ответов запрещает безусловные обещания. Ответы проверяют оценщик диалогов и стенд оценки (eval harness);
• персональные данные удаляются, число циклов вызова инструментов ограничено. Агент выпущен с выключенным флагом функции и не влияет на бота до включения.

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

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

В панели управления оператор находит пользователя по Telegram id, username, id подключения или коду активации. В одном обзоре видны пользователь, подписка, учётные данные подключения, связанные контексты и состояние. Там же доступны разрешённые оператору действия.

Также есть бот оператора, разделы админки для подписок, пользователей, промокодов, реселлеров, поддержки и отмен. Отдельный сервис сверяет и восстанавливает зависшие аккаунты, внутренний канал получает оповещения. Выводы и возвраты исполняет оператор. Дедупликация защищает от повторной выплаты по одному запросу. Для чувствительных действий нужно указать причину. Токены удаляются из вывода на экран и в журнал.

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

Рассылки учитывают этап работы пользователя с сервисом. Цепочки и массовые кампании, подсказки при настройке, напоминания о незавершённом подключении, пробном и платном периодах и возврат неактивных пользователей используют общий маршрут отправки с сегментацией и лимитом частоты. Транзакционные сообщения, например личное уведомление о сбое, этот лимит обходят.

Аналитика роста тоже встроена: A/B-тесты, удержание по когортам и отчёты по воронкам для оплаты, настройки и конверсии в платёж, плюс экран юнит-экономики.

Мониторинг построен на Prometheus, Grafana, Loki/Promtail и Alertmanager, оповещения приходят в Telegram. Кроме метрик CPU, базы данных и контейнеров я добавил проверки срока TLS-сертификатов и доступных локаций, которые не пропускают трафик. Есть оповещения о состоянии узлов и метрики резервных копий вне сервера.

Резервные копии сохраняются вне сервера. По расписанию проверяется их восстановление. Выпуски выполняются через продакшен-раннер с фиксированным SHA, с чек-листом, флагами запуска и регламентами (runbook) отката и действий при сбое. Если состояние сессии или реплики расходится с ожидаемым, механизмы сверки запускают восстановление.