How We Built a Telegram Mini App for 7,000+ African Users
When we started building our Telegram gambling platform in late 2023, there was no playbook. No tutorial, no reference architecture, no open-source starter kit. The Telegram Mini App ecosystem was still young, and nobody had built a real-money gambling product for the Ethiopian market inside it. We had to figure out everything from first principles.
This article is the technical breakdown we wish we had when we started.
Why Telegram Over a Native App
The decision to build inside Telegram was not aesthetic — it was strategic. In Ethiopia, app distribution is a real problem. The Google Play Store has restrictive policies around gambling apps. Sideloading APKs requires user education. And building for iOS means navigating Apple's even stricter review process.
Telegram, on the other hand, has massive penetration across Ethiopia. Users already have it installed. They already trust it. And Telegram's Mini App platform lets you deliver a full web application experience inside a chat window — no app store needed, no installation friction, no review process.
The tradeoff is clear: you lose some native capabilities, but you gain instant distribution to millions of existing Telegram users. For the Ethiopian gambling market, that tradeoff is overwhelmingly positive.
The Technical Architecture
Our stack is straightforward but battle-tested:
- •Frontend: Next.js running as the Telegram Mini App WebApp
- •Backend: Node.js with Express, handling game logic, transactions, and agent management
- •Database: Supabase (PostgreSQL) for persistent state
- •Bot Layer: Telegram Bot API for notifications, commands, and session management
- •Hosting: Render for both frontend and backend services
The Mini App loads inside Telegram's WebApp container. We authenticate users through Telegram's initData validation — every request carries a signed payload from Telegram that we verify server-side. This eliminates the need for traditional auth flows. Users never create an account. They just open the bot, tap "Play," and they are in.
The Hardest Problem: Real Money Inside a Sandbox
Telegram's WebApp environment is sandboxed. You cannot redirect users to external payment pages in the traditional sense. You cannot pop up a bank app. The user experience must stay inside the Telegram window.
Our solution was to build a deposit flow that works entirely within the Mini App UI. Users select a payment method — Telebirr, bank transfer, or agent deposit — and we generate transaction references server-side. For Telebirr, we integrate their USSD-based payment confirmation. For bank transfers, we generate a unique reference code and verify deposits through a manual reconciliation system backed by our agent network.
The agent deposit system turned out to be the most reliable channel. Agents — local operators who manage player accounts — can credit player balances directly through a dedicated agent interface. This mirrors how betting shops work in Ethiopia, translated into a digital flow.
Concurrent Sessions and Balance Synchronization
When a player has 500 ETB in their account, they should not be able to bet 500 ETB in Loterya and 500 ETB in Shekosh simultaneously. This sounds obvious, but implementing it correctly inside a system where three different games can be played concurrently is genuinely difficult.
We solved this with a pessimistic locking strategy at the database level. Every bet placement acquires a row-level lock on the player's balance record. If two concurrent bet requests arrive, the second one waits for the first to complete. We set aggressive timeouts (2 seconds) to prevent deadlocks from degrading the user experience.
For the game state itself, we maintain separate game session records that reference the player's locked balance. When a game round completes, the result is calculated, the balance is updated atomically, and the lock is released. The entire flow — from bet placement to result settlement — runs inside a database transaction.
Building the Agent Network
The agent system is perhaps the most uniquely African aspect of our platform. In established betting markets, users deposit money through credit cards or bank APIs. In Ethiopia, the most common money movement happens through people.
We built a three-tier agent hierarchy: super agents manage regional agents, who manage local agents, who interact directly with players. Each agent has a dedicated dashboard showing their network's activity, their commission balance, and tools to credit or debit player accounts.
Commission calculation runs in real time. When a player under Agent A makes a bet, a percentage flows up through the hierarchy — Agent A gets their cut, the regional agent above them gets a smaller cut, and the super agent gets the smallest cut. This is calculated and credited at the moment the bet settles, not in batch. Agents can see their earnings update in real time, which builds trust.
What We Would Do Differently
If we were starting today, we would invest more in observability from day one. We built the monitoring system after we had real users, which meant our first few weeks of production were partially blind. We now have comprehensive logging, but retrofitting observability is always harder than building it in.
We would also abstract the payment integration earlier. Our first implementation was tightly coupled to specific payment methods. When we added new payment rails, we had to touch more code than necessary. A proper payment abstraction layer from the start would have saved us several days of refactoring.
Lessons for Other Developers
If you are building a Telegram Mini App for African users, here is what matters:
- •Assume 3G connections. Test everything on throttled networks. If your app takes more than 3 seconds to load on a 5 Mbps connection, you will lose users.
- •Telegram's initData is your auth layer. Do not build a separate auth system. Validate initData on every API call and use the Telegram user ID as your primary user identifier.
- •Design for agents, not just end users. In African markets, intermediaries are part of the business model. Build tools for them from day one.
- •Reconciliation is a feature. Payment reconciliation in Ethiopia is not automatic. Build manual verification tools and make them first-class features, not afterthoughts.
The Telegram Mini App platform is genuinely powerful for African distribution. The technical challenges are real, but they are solvable. What matters is understanding the market you are building for — and building accordingly.