Como Unificar Bot e Mini App do Telegram com Next.js

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.

Por que escolher Next.js para desenvolver Bots e Mini Apps unificados?

No modo tradicional, os desenvolvedores precisam:

• Implantar o serviço de backend do Bot separadamente
• Implantar o aplicativo frontend do Mini App separadamente
• Lidar com a integração de dados entre os dois projetos
• Manter dois conjuntos de variáveis de ambiente e configurações

Com a solução unificada do Next.js, você pode:

• Gerenciar todas as funcionalidades em um único repositório de código
• Compartilhar rotas de API para lidar com comandos de Bot, solicitações de Mini App e lógica de pagamento
• Implantar unificadamente em plataformas como Vercel, reduzindo os custos operacionais
• Dados naturalmente integrados, sem necessidade de mecanismos de sincronização adicionais

Essa abordagem é particularmente adequada para validar rapidamente ideias, desenvolver produtos MVP ou para desenvolvedores independentes lançarem projetos rapidamente.

---

Demonstração de Funcionalidade Principal: O que este projeto pode fazer?

Construiremos um sistema de jogos de pontos com as seguintes funcionalidades:

• Recompensa de Check-in Diário: Os usuários podem resgatar 100 pontos a cada 24 horas, com exibição de contagem regressiva em tempo real.
• Pagamento com Telegram Stars: Os usuários compram pontos com dinheiro real, com suporte para testes de reembolso instantâneos.
• Processamento de Comandos do Bot: Suporta comandos comuns como /start, /help, com um clique para iniciar o Mini App.
• Notificações em Tempo Real: Operações como sucesso de pagamento e conclusão de reembolso enviarão notificações de mensagens através do Bot.

Todo o sistema é executado em um único aplicativo Next.js, com interação totalmente transparente entre o Bot e o Mini App.

---

Pré-requisitos para Começar

Antes de iniciar o desenvolvimento formal, você precisará preparar as seguintes ferramentas:

1. Conta Telegram: Para criar Bots e testar Mini Apps.
2. Node.js 18+: Se não estiver instalado, visite nodejs.org para baixar.
3. Ngrok: Para criar um túnel HTTPS durante o desenvolvimento local, pois o Telegram exige HTTPS para Webhooks e Mini Apps.

Como obter o Ngrok

• Visite ngrok.com e registre uma conta gratuita.
• Baixe a versão compatível com o seu sistema operacional.
• Descompacte-o em uma pasta dedicada.
• Execute ngrok config add-authtoken <seu_token> para vincular sua conta.
• Concluído isso, você pode executar ngrok http 3000 a qualquer momento nesta pasta.

---

Configuração Rápida do Projeto (Pronto em 5 Minutos)

1. Obtenha o Código do Projeto e Instale as Dependências

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

2. Configure as Variáveis de Ambiente

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.

3. Crie um Bot Telegram

• Abra o Telegram e procure por BotFather.
• Envie /newbot para criar um novo Bot.
• Defina o nome e o nome de usuário do Bot (deve terminar com bot).
• Copie o Token do Bot gerado e salve-o em .env.local.

4. Inicie o Ngrok e o Servidor de Desenvolvimento

# 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".

5. Configure o Botão de Menu do Mini App

• Volte para o BotFather, envie /mybots e selecione seu Bot.
• Clique em Bot Settings → Menu Button.
• Preencha a URL (use o endereço HTTPS fornecido pelo Ngrok) e o texto do botão (por exemplo, "Play Game").

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!

---

Análise do Código Central: Como Bots e Mini Apps Trabalham em Conjunto?

Ponto de Extremidade do Webhook: O Hub de Mensagens do Bot

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:

• Comandos de Usuário: /start, /help, etc.
• Confirmação pré-pagamento: Verificação preliminar após o usuário clicar no botão de pagamento.
• Callback de pagamento bem-sucedido: Confirmação da conclusão da transação e emissão de pontos.
• Solicitação de reembolso: Teste rápido do fluxo de reembolso durante o desenvolvimento.

Quando um usuário envia /start pela primeira vez, o Bot enviará imediatamente um botão "Iniciar Jogo", sem necessidade de orientação adicional.

Fluxo de Pagamento com Telegram Stars

A funcionalidade de pagamento está centrada na rota /api/buy-points:

1. O usuário clica em "Comprar Pontos" no Mini App.
2. A API do Bot Telegram é chamada para criar uma fatura (createInvoiceLink).
3. A fatura é exibida na interface de pagamento nativa do Telegram.
4. Após o usuário concluir o pagamento, o Webhook recebe a notificação.
5. O sistema atualiza os pontos do usuário e envia uma mensagem de recibo.

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.

Sistema de Recompensa de Check-in Diário

Na rota /api/claim-daily, implementamos um mecanismo de incentivo baseado em tempo:

• Registra o tempo da última retirada de cada usuário.
• Verifica se já se passaram 24 horas.
• Se ainda não se passaram 24 horas, retorna o tempo restante na contagem regressiva.
• Ao retirar com sucesso, emite 100 pontos e envia uma notificação do Telegram.

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.).

---

Considerações sobre Implantação em Ambiente de Produção

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:

• Banco de Dados: Use PostgreSQL ou MongoDB em vez de armazenamento em memória.
• Autenticação de Usuário: Valide a assinatura dos dados do Telegram Web App para evitar solicitações forjadas.
• Proteção contra Limitação de Taxa: Evite roubo de pontos malicioso ou abuso da interface de pagamento.
• Monitoramento de Logs: Integre serviços de rastreamento de erros (como Sentry).
• Segurança do Webhook: Verifique se a origem da solicitação é realmente o servidor Telegram.

Plataformas de implantação recomendadas:

• Vercel: Implantação sem configuração, HTTPS automático.
• Heroku / Railway: Adequado para cenários que exigem conexões longas.
• Cloudflare Workers: Solução de computação de ponta, aceleração global.

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.

---

Perguntas Frequentes (FAQ)

Por que o Ngrok é necessário? O localhost não funciona?

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.

Como testar pagamentos reais sem gastar dinheiro?

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.

Posso continuar usando armazenamento em memória no ambiente de produção?

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.

Quais são as principais vantagens da solução unificada Next.js?

A maior vantagem é a eficiência de desenvolvimento e a redução dos custos de manutenção. Você não precisa:

• Gerenciar dois repositórios de código
• Se preocupar com inconsistência de dados entre frontend e backend
• Configurar complexas integrações cross-origin e de API
• Implantar e monitorar dois serviços separadamente

Toda a lógica está em um único projeto, com alta reutilização de código e depuração mais rápida de bugs.

Essa arquitetura é adequada para aplicações em larga escala?

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.

---

Conclusão

Através da demonstração prática deste artigo, você dominou as habilidades essenciais para construir um aplicativo unificado de Bot Telegram + Mini App usando Next.js. Essa abordagem de desenvolvimento pode ajudá-lo a validar ideias rapidamente, reduzir os custos de desenvolvimento e lançar uma base sólida para expansões futuras. Comece a experimentar agora e crie seu próprio mini-jogo Telegram no menor tempo possível!