Como construir um Telegram Mini App em 2026: do protótipo a 60.000 usuários diários

Os Telegram Mini Apps cresceram de uma feature experimental para uma plataforma de distribuição real: 200 milhões de usuários os abrem todo mês, e é a forma que mais cresce para entregar um produto dentro do messenger. Lançamos o The Open Earn no começo de 2024 e o crescemos para 60.000 usuários ativos diários e mais de 500.000 tarefas concluídas em 18 meses. Este guia é o que fizemos e o que diríamos a nós mesmos no dia um.

Mini App vs bot comum: quando escolher qual

Um Telegram Bot é uma interface de chat sobre mensagens. Um Telegram Mini App é uma aplicação web completa que abre dentro do Telegram e tem acesso à API do messenger.

Um bot comum basta quando:

• O fluxo é linear: comandos → respostas (bot de escrow, bot de notificações)
• A complexidade de UI é mínima
• A velocidade de protótipo importa

Você precisa de um Mini App quando:

• UI complexa com navegação, formulários, listas
• Interatividade em tempo real
• Pagamentos via Telegram Payments ou Stars
• Catálogos de produtos, perfis de usuário, feeds

No The Open Earn rodamos ambos: um bot para notificações e onboarding, um Mini App para a interface principal (saldo, saque, estatísticas).

Stack: o que realmente usamos

A stack de produção do The Open Earn, sem enrolação de marketing:

Frontend (Mini App):

• Next.js 16 (App Router, SSR) — para primeiro paint rápido e SEO na landing
• React 19 + TypeScript
• @twa-dev/sdk — wrapper em volta do SDK Telegram Web Apps (tema, viewport, eventos)
• TonConnect SDK — para conectar a carteira TON do usuário

Backend:

• Python 3.12 + FastAPI — servidor API
• aiogram 3.x — o bot
• PostgreSQL 16 — armazenamento principal
• Redis — cache de sessão, rate limiting, pub/sub para workers
• Celery — jobs em background (payouts, verificação de tarefas)

Infraestrutura:

• Um servidor dedicado (8 GB RAM, 4 vCPU)
• nginx como reverse proxy
• PM2 para processos Node, systemd para Python
• Let's Encrypt para SSL

Isso aguenta até 50–100K DAU. Só tivemos que fazer upgrade quando passamos de 60K — movemos o Postgres para uma managed instance.

Autenticação: initData e validação no servidor

O erro de novato mais comum: confiar em Telegram.WebApp.initDataUnsafe. Isso é falsificável no DevTools.

O fluxo correto:

1. O Mini App recebe o initData (raw string) do Telegram via o JS SDK ao iniciar
2. Ele envia isso para seu backend em Authorization: TelegramInitData ...
3. O backend valida a assinatura com HMAC-SHA256 baseado no bot token
4. Em assinatura válida — extrai user.id e emite um token de sessão

Validação em Python:

import hmac, hashlib
from urllib.parse import parse_qs

def validate_init_data(init_data: str, bot_token: str) -> dict:
    parsed = parse_qs(init_data)
    received_hash = parsed.pop("hash")[0]
    data_check = "\n".join(f"{k}={v[0]}" for k, v in sorted(parsed.items()))
    secret = hmac.new(b"WebAppData", bot_token.encode(), hashlib.sha256).digest()
    expected = hmac.new(secret, data_check.encode(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, received_hash):
        raise ValueError("Invalid signature")
    return parsed

Verifique também o auth_date — descarte sessões com mais de 24 horas (proteção contra replay).

Pagamentos: Stars, TON, USDT

Três formas reais de receber dinheiro dentro do ecossistema Telegram em 2026:

1. Telegram Stars (para bens digitais) — via Bot API: sendInvoice com currency: "XTR". Apenas compras intangíveis. O Telegram fica com ~30%.

2. TON diretamente — via TonConnect: o usuário conecta uma carteira e assina a transação. Taxas são frações de centavo.

3. USDT na TON (Jetton) — igual a TON mas como stablecoin. Útil para B2B e cobrança a preço fixo.

No The Open Earn pagamos os ganhos em USDT via TonConnect — os usuários veem um valor em dólares, não um preço TON flutuante. Saque mínimo: $1.

Deploy e scaling

O layout de produção mais simples para os primeiros 10K DAU:

[Cloudflare] → [nginx] → [Next.js on :3000] → [FastAPI on :8000] → [Postgres]
                                                  ↓
                                              [Redis]

O que quebrou para nós a 30K DAU e como consertamos:

• Postgres connection pool acabava — adicionamos pgbouncer e dividimos read/write
• Redis OOM durante picos — aumentamos o maxmemory, mudamos para allkeys-lru
• Latência do webhook do bot — movemos checagens pesadas para Celery
• CDN de static assets — empurramos para Cloudflare R2

A única regra que importa: meça, não chute. Sentry para erros, Grafana + Prometheus para métricas, desde o dia um.

O que faríamos diferente

Se estivéssemos começando de novo no dia um:

1. Dividir em 2 serviços desde o começo — API pública (Mini App) e privada (admin/workers). Juntar é mais barato do que separar depois.
2. Lançar feature flags desde o dia um (Unleash, GrowthBook) — teria sido útil para A/B tests durante o crescimento.
3. Usar Next.js Server Actions em vez de uma camada REST custom para formulários simples. Menos código.
4. Pular as animações bonitas no dia um — usuários vêm pela função, não pelo polimento. Polimento faz sentido depois do product-market fit.
5. Construir i18n desde o dia um — traduções em 12 idiomas multiplicaram nosso tráfego por 4×, mas adicioná-las depois foi doloroso.

O que vem a seguir

Mini Apps em 2026 não são mais "o experimento do Telegram" — são um canal de distribuição real. Se seu produto se sobrepõe à audiência ativa do messenger, vale ao menos um protótipo. A stack inicial é pequena, o risco é menor do que o de um app mobile nativo.

Se quiser ver como isso parece em produção — abra The Open Earn ou pule direto para o bot.