A Telegram-native subscription service I built: every feature, end to end

Onboarding is a guided rail, not a wall of text. The bot welcomes the user from a deep link, which can carry a referral code. The Mini App then runs a short wizard: choose a plan or a trial, then install a client, then import the subscription link or scan the QR.

The service detects the user’s platform from what Telegram already tells the client — Android, iOS, Windows or macOS — and serves the right install instructions and a deep link into the recommended client app. A first-run user can take a free trial: 3 days, once per person. If they are not eligible, the app says why and shows the plans instead of blocking them.

The most important part is honesty. The system confirms that a connection actually works before it congratulates the user, and it nudges people who started setup and stopped rather than leaving them stuck.

Plans come in monthly, quarterly and yearly terms, with a Standard tier and a Pro tier. A plan carries its own device allowance, and Pro raises it to 10 devices. Add-ons such as a dedicated IP sit on top of the plan.

The subscription record is the entitlement: which plan, when it started, when it expires, whether it renews, and how many payment attempts have run. A plan can be migrated to a new price grid while the paid period is grandfathered, so an existing subscriber keeps the terms they paid for until the period ends.

There is also a family plan, business seats with their own cabinet, gift subscriptions, promo codes and loyalty tiers. Each of those is a distinct product surface on top of the same billing core, not a separate system.

The trial and paid states share one lifecycle: when a subscription ends, the network and its devices are preserved and only transport is revoked, so reactivation does not mean re-creating everything.

Payments are the part I spent the most time making boring and safe. The service accepts card and instant bank payments, Telegram’s in-app currency, crypto, and a web checkout outside Telegram. Whatever the rail, every payment creation endpoint is guarded by durable request-level idempotency: a repeated request with the same key returns the original result instead of charging twice, a request still in flight is reported as such, and a key reused with a different payload is refused. A stale worker loses its processing lease rather than writing a second charge.

Behind the payment providers sits a proper billing domain:

• one account balance per user, with an append-only ledger (top-up, subscription charge, refund, promo credit, referral credit, adjustment, withdrawal debit, correction) so money history is never edited in place;
• invoices and charges that record what is owed and each attempt to collect it, with saved payment methods for later use;
• renewal modes: manual, balance-first, balance-first with automatic top-up, and direct autopay — plus retries and a grace period, handled by a dedicated renewal service rather than ad-hoc cleanup;
• self-service refunds with an eligibility check, a ledger entry for the reversal, and a reversal of any referral reward that the refunded payment had generated;
• a pending-payment policy: if a payment is stuck, the user is offered a clear choice rather than left in limbo.

After payment the user gets a delivery step, not just a receipt: the connection link, a QR code and platform-specific setup, with the backend verifying the payment before it shows success.

Identity is Telegram-first, with several ways in. The Mini App authenticates from Telegram; a user can also sign in with Telegram OIDC, Google or another OAuth provider, a magic link, or an email binding. When the same person arrives twice — once from the web checkout and once from Telegram — the accounts are linked and merged automatically instead of silently splitting the subscription, which is a bug class I removed on purpose.

Devices are first-class. Each subscription owns a fixed set of device slots, and each device gets its own connection credential and its own transport binding, so losing one device does not mean reissuing the others. A user can add, rename and remove a device, and upgrade the device allowance; a wizard walks through the add. Universal (shared) access stays available as a first-class option and is never labelled as an old mode.

The Access area hands out the subscription link and QR once, and the service reissues or rotates it when a token needs to change. A connection test and a troubleshooting flow sit next to the setup guides so a user can prove a device works before asking for help.

Routing and regions live here too: choosing the exit country, per-service routing, content filters, an ad-free routing option and a dedicated IP, plus a last-seen view of each device.

Referral is built into the product, not bolted on. Every user gets an 8-character referral code and a link; a referred person goes through a pending → active lifecycle that flips on their first payment; and the referrer earns a share of each of their payments, at a default of 20%, with individual rates up to 50% for VIP partners. A referred newcomer can receive a small spend-only bonus that can be used on a purchase but cannot be withdrawn. Balances can be paid out through withdrawal requests that an operator reviews and settles.

A separate affiliate programme tracks paid partners with two commission tiers and its own payout requests.

Resellers get a dashboard of their own clients, an individual commission rate, and the same withdrawal flow, all reviewed by the operator.

Promo codes are applied server-side. A code can be a percentage or a fixed amount, can be scoped to one plan, and carries usage and expiry limits, with auto-apply for launch campaigns.

Gifts let a user buy a subscription for someone else: the recipient gets a 12-character code with a 180-day redemption window. Family plans and business seats build on the same core, with a B2B cabinet for seat management. Loyalty tiers reward long-running subscribers.

Support has a human path and an AI path, and the AI one is deliberately cautious.

The AI support agent runs a manual agent loop over an OpenAI-compatible model with tool calls into real account state — subscription, devices, server nodes, the subscription link and the current tariffs — plus a knowledge base for how-to answers. Its rules are the interesting part:

• facts about an account come only from tools, never from the model’s memory;
• setup instructions come only from the knowledge base;
• prices and plan contents are read live, never recalled;
• user text is treated as data, not as instructions, so a message that says “ignore your rules” does not change them;
• destructive actions are two-phase: the agent previews the change, waits for a clear yes, then applies it;
• it escalates to a human instead of guessing when money, account security or an angry user is involved;
• an honesty gate forbids absolute promises, and a dialog judge plus an eval harness score answers against those rules;
• PII is scrubbed, tool loops are capped, and the whole agent ships dark behind a flag, so it has zero effect on the bot until it is switched on.

On the human side there are support tickets, an operator handoff, bug reports, feature requests, feedback and cancellation reasons.

Support is also proactive. Watchdogs detect when a server location stops carrying traffic — not merely when its panel is alive — and the bot can message the affected subscribers first, in honest language that does not promise a fix time and does not claim to have moved them automatically. A public status page shows server state.

The operator surface is a cockpit, not a pile of SQL. One search box finds a user by Telegram id, username, connection id or activation code and returns a single overview: the user, the subscription, the connection credential, the contexts they belong to, and health flags — plus the actions an operator is allowed to take.

Around it sit an operator bot, admin screens for subscriptions, users, promo codes, resellers, support and cancellations, a repair service for reconciling a stuck account, and an internal-alert channel. Withdrawals and refunds are reviewed and settled by an operator, with dedup so the same request is never paid twice. Sensitive actions require a reason, and logging is scrubbed so raw tokens never reach an operator screen or a log line.

A background worker runs the machinery that keeps the service honest: reconcilers that keep the server fleet, content filters, ad-free routing and subscription replicas in sync with the database; schedulers for daily billing, subscription tasks, pending-payment policy, presence collection and key-status drift.

Messaging is lifecycle-driven. Drip and broadcast campaigns, onboarding nudges, abandoned-setup reminders, trial and paid notifications, dormancy win-back and segmentation all run through one dispatch path with a global frequency cap — except transactional messages such as an incident DM, which are allowed through on purpose.

Growth analytics are built in too: A/B tests, cohort retention, and funnel reports for checkout, setup and payment conversion, plus a unit-economics view.

The service is watched with Prometheus, Grafana, Loki/Promtail and Alertmanager, with alerts delivered to Telegram. On top of the standard CPU, database and container metrics there are purpose-built checks: TLS certificate expiry, a “dead entry / black hole” detector that catches a location which is reachable but carries no traffic, node-health alerts, and metrics for the off-box backups.

Backups leave the box and are restored on a schedule, not just taken. Deploys go through an immutable-SHA production runner with a release checklist, dark-launch feature flags, and rollback and incident runbooks. The reconcilers give the system a self-healing loop when a session or a replica drifts.