Ao desenvolver no ecossistema Telegram, muitos desenvolvedores enfrentam um ponto de dor comum: como gerenciar dois conjuntos de código para Bot e Mini App simultaneamente? A abordagem tradicional envolve a implantação separada de dois projetos, o que não só aumenta os custos de manutenção, mas também pode levar a problemas na sincronização de dados e nos fluxos de pagamento.
Este artigo apresentará uma nova abordagem de desenvolvimento: usar um único projeto Next.js para implementar simultaneamente um Bot Telegram e um Mini App, alcançando verdadeiramente um conjunto de código, uma implantação, integração perfeita. Você aprenderá a construir um sistema completo de jogos de pontos, incluindo recompensas de check-in diário, pagamentos reais com Telegram Stars e funcionalidade de notificação em tempo real.
No modo tradicional, os desenvolvedores precisam:
Com a solução unificada do Next.js, você pode:
Essa abordagem é particularmente adequada para validar rapidamente ideias, desenvolver produtos MVP ou para desenvolvedores independentes lançarem projetos rapidamente.
Construiremos um sistema de jogos de pontos com as seguintes funcionalidades:
/start, /help, com um clique para iniciar o Mini App.Todo o sistema é executado em um único aplicativo Next.js, com interação totalmente transparente entre o Bot e o Mini App.
Antes de iniciar o desenvolvimento formal, você precisará preparar as seguintes ferramentas:
ngrok config add-authtoken <seu_token> para vincular sua conta.ngrok http 3000 a qualquer momento nesta pasta.Você pode obter o código-fonte completo e a documentação detalhada dos canais relevantes do Telegram (o link específico pode ser encontrado na descrição do vídeo original).
git clone <endereço_do_repositório_do_projeto>
cd <diretório_do_projeto>
npm install
Crie um arquivo .env.local na raiz do projeto para armazenar informações confidenciais:
TELEGRAM_BOT_TOKEN=seu_token_de_bot
NEXT_PUBLIC_APP_URL=seu_endereço_ngrok
Aviso Importante: Certifique-se de que .env.local esteja adicionado ao .gitignore para evitar a exposição do Token do Bot.
/newbot para criar um novo Bot.bot)..env.local.# Terminal 1: Inicie o Ngrok
ngrok http 3000
# Terminal 2: Inicie o servidor de desenvolvimento Next.js
npm run dev
# Terminal 3: Configure o Webhook
npm run webhook:setup
Se tudo ocorrer bem, você verá a mensagem "Webhook set successfully".
/mybots e selecione seu Bot.Agora, quando os usuários abrirem seu Bot, eles verão um botão para iniciar o jogo. Clicar nele os levará à interface do Mini App!
Todas as atualizações enviadas pelo Telegram (comandos de usuário, callbacks de pagamento, etc.) serão encaminhadas para a rota /api/telegram/webhook através do Webhook.
Os principais tipos de mensagens processadas incluem:
/start, /help, etc.Quando um usuário envia /start pela primeira vez, o Bot enviará imediatamente um botão "Iniciar Jogo", sem necessidade de orientação adicional.
A funcionalidade de pagamento está centrada na rota /api/buy-points:
createInvoiceLink).Configuração Chave:
provider_token deixado em branco (modo Telegram Stars).currency definido como XTR.prices em unidades de Stars (não centavos).Benefício para Desenvolvedores: Após cada compra, um ID de recibo é retornado, permitindo que você teste imediatamente o reembolso com o comando /refund <ID_do_Recibo>, sem esperar por aprovação ou processamento manual. Isso é extremamente eficiente para testar o fluxo de pagamento real.
Na rota /api/claim-daily, implementamos um mecanismo de incentivo baseado em tempo:
O frontend usa um componente de contagem regressiva em tempo real que atualiza o tempo restante a cada segundo, informando claramente aos usuários quando eles podem retirar novamente. Esse padrão pode ser estendido para qualquer jogabilidade que exija limitações de tempo (como recuperação de energia, cooldown de sorteio, etc.).
Embora este artigo use armazenamento em memória para demonstração, é imperativo fazer as seguintes modificações antes de colocar o projeto em produção:
Plataformas de implantação recomendadas:
Ao implantar, lembre-se de atualizar a URL do Webhook e o link do botão do Menu do Mini App para o seu domínio de produção.
Os Webhooks e Mini Apps do Telegram exigem o protocolo HTTPS. O localhost não atende a esse requisito. O Ngrok pode criar um túnel HTTPS acessível pela rede pública, encaminhando solicitações para o seu servidor de desenvolvimento local.
Durante a fase de desenvolvimento, você pode comprar uma pequena quantidade de Telegram Stars (a partir de alguns centavos) e, em seguida, usar o comando /refund para reembolsar imediatamente. Isso permite testar os fluxos de pagamento, callbacks de Webhook e lógica de reembolso com um processo real, sem a necessidade de recargas repetidas.
Absolutamente não. O armazenamento em memória perde todos os dados quando o servidor é reiniciado. É crucial usar um banco de dados persistente (como PostgreSQL) e ter planos de backup e migração.
A maior vantagem é a eficiência de desenvolvimento e a redução dos custos de manutenção. Você não precisa:
Toda a lógica está em um único projeto, com alta reutilização de código e depuração mais rápida de bugs.
Para produtos MVP e aplicações de pequeno a médio porte, é totalmente suficiente. Se o número de usuários ativos diários atingir milhões, é recomendável separar o backend do Bot e o frontend do Mini App, utilizando uma arquitetura de microsserviços e filas de mensagens dedicadas para lidar com alta concorrência.
Esboço
