Como criar seu primeiro Mini App do Telegram: guia passo a passo

Telegram vs. WeChat: a disputa entre os superapps

Há anos, o WeChat é o líder incontestável entre os superapps. Lançado em 2011, tornou-se parte essencial do dia a dia na China ao reunir mensagens, redes sociais, pagamentos e comércio eletrônico em uma única plataforma. O Telegram chegou depois, em 2013, mas vem ganhando espaço rapidamente e já desponta como um forte concorrente no cenário global dos superapps. Hoje, desenvolvedores podem criar serviços inovadores e até desenvolver minissoluções diretamente no Telegram. Com a documentação certa sobre Mini Apps, quem quiser criar um novo bot do Telegram ou desenvolver um Mini App usando tecnologias web conhecidas pode começar a criar aplicativos com mais facilidade do que nunca.

Principais diferenças entre Telegram e WeChat:

O WeChat domina há muito tempo o mercado chinês como um app que reúne tudo em um só lugar, mas o Telegram está avançando com força para disputar espaço no cenário global. Com foco em privacidade, recursos de ponta e ferramentas para desenvolvedores, o Telegram vem conquistando um espaço próprio. Com os Mini Apps do Telegram (TMA), agora os desenvolvedores podem criar aplicativos web que se integram perfeitamente à plataforma, ajudando o Telegram a diminuir a distância rapidamente e a conquistar usuários no mundo todo.

Agora, vamos ver como criar um Mini App do Telegram e fazer parte dessa comunidade crescente de desenvolvedores que aproveitam todo o potencial da plataforma.

O que são os Mini Apps do Telegram e por que fazem tanto sucesso?

Mini Apps do Telegram (TMA) são, basicamente, aplicativos web que funcionam dentro do Telegram. Pense neles como sites tradicionais, criados com HTML, CSS e JavaScript, mas que podem acessar recursos exclusivos do Telegram por meio do SDK. Eles são abertos dentro do Telegram e oferecem uma experiência integrada, integração de dados e sistemas de pagamento nativos. Para usar o Telegram com Mini Apps, os desenvolvedores geralmente criam um bot pelo BotFather, escolhem um nome de usuário e ajustam as configurações para conectar o bot ao aplicativo. Depois de configurados, os Mini Apps podem ser compartilhados em grupos do Telegram ou diretamente com usuários, ampliando as possibilidades do ecossistema. Entender como os Mini Apps do Telegram funcionam é essencial para quem quer aproveitar essa plataforma.

Por que os desenvolvedores adoram os TMA:

Exemplos de Mini Apps do Telegram de sucesso

Veja alguns exemplos reais do que é possível fazer:

• Wallet — exemplo de serviço de carteira acessado pelo Telegram; os recursos variam conforme a carteira e a região.
• Hamster Kombat — jogo de tocar na tela que atraiu um enorme engajamento.
• DurgerKing — Mini App de demonstração do Telegram para testar um fluxo de pedidos e pagamentos de comida.

Como começar a criar Mini Apps do Telegram

O que você precisa:

• Um editor de código (VS Code ou WebStorm, por exemplo).
• Conhecimentos básicos de HTML, CSS e JavaScript.
• Telegram instalado no celular e no computador.
• Vontade de explorar algo novo.

Etapa 1: crie um bot auxiliar

Sua jornada começa com a criação de um bot do Telegram. Ele será a porta de entrada para o seu aplicativo. Veja como criar um:

1. Pesquise por @BotFather no Telegram.
2. Envie o comando /newbot.
3. Escolha um nome para o bot.
4. Guarde em segurança no seu servidor o token fornecido pelo BotFather — você vai precisar dele para usar a Bot API. Nunca o inclua no código do navegador nem em um repositório público.

Abaixo está o código Node.js para o seu servidor. Instale o node-telegram-bot-api, defina o token usando uma variável de ambiente no servidor e substitua https://your-domain.com/app pela URL HTTPS publicada antes de executar o código. O botão inline web_app foi feito para uma conversa privada com o bot:

javascript
const TelegramBot = require('node-telegram-bot-api');
const bot = new TelegramBot(token, { polling: true });

bot.onText(/\\/start/, (msg) => {
const chatId = msg.chat.id;
bot.sendMessage(chatId, 'Boas-vindas! Clique no botão abaixo para abrir o app.', {
reply_markup: {
inline_keyboard: [[
{
text: 'Abrir app',
web_app: { url: 'https://your-domain.com/app' }
}
]]
}
});
});

Etapa 2: configure o ambiente

Crie uma estrutura básica de projeto para desenvolver um mini app do Telegram e configurar o ambiente de testes:

Estrutura de diretórios do projeto (o conteúdo de index.html aparece na Etapa 3):

text
my-tma/
├── index.html
├── styles/
│ └── main.css
├── scripts/
│ └── app.js
└── assets/
└── images/

Etapa 3: crie seu app

Salve este HTML como index.html. Ele carrega a bridge do Telegram WebApp e o arquivo scripts/app.js. Este é apenas um exemplo de interface, não uma implementação de autenticação: valide o initData do Telegram no backend antes de confiar na identidade do usuário.
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Meu primeiro TMA</title>
<link rel="stylesheet" href="styles/main.css">
<script src="https://telegram.org/js/telegram-web-app.js"></script>
</head>
<body>
<div id="app">
<h1>Olá, Telegram!</h1>
</div>
<script src="scripts/app.js"></script>
</body>
</html>

Personalizando o visual do app

Salve o código JavaScript a seguir como scripts/app.js. setupTheme aplica as cores do tema do Telegram, enquanto styles/main.css é uma folha de estilos separada que você pode personalizar. Teste no Telegram para Android e iOS. Importante: sendData só funciona em Mini Apps abertas por um botão web_app no teclado de resposta, não pelo botão inline da Etapa 1. Para salvar dados quando o app é aberto pelo botão inline, implemente um endpoint no backend e valide initData. Este exemplo não persiste dados nem processa mensagens web_app_data recebidas:

javascript
const app = {
data: { count: 0 },

init() {
this.setupTheme();
this.setupCounter();
this.setupMainButton();
},

setupTheme() {
const theme = window.Telegram.WebApp.themeParams;
document.body.style.backgroundColor = theme.bg_color;
document.body.style.color = theme.text_color;
},

setupCounter() {
const counter = document.createElement('div');
counter.innerHTML = `
<h2>Contador: <span id="count">0</span></h2>
<button id="increment">+1</button>
<button id="decrement">-1</button>
`;
document.querySelector('#app').appendChild(counter);

document.querySelector('#increment').onclick = () => this.updateCount(1);
document.querySelector('#decrement').onclick = () => this.updateCount(-1);
},

setupMainButton() {
const MainButton = window.Telegram.WebApp.MainButton;
MainButton.setText('Salvar');
MainButton.onClick(() => this.saveData());
MainButton.show();
},

updateCount(delta) {
this.data.count += delta;
document.querySelector('#count').textContent = this.data.count;
},

saveData() {
window.Telegram.WebApp.sendData(JSON.stringify(this.data));
}
};

window.Telegram.WebApp.ready();
app.init();

Expandindo as funcionalidades

Depois de montar a base, você pode aprimorar seu Mini App com recursos avançados:

• Adicione recursos Web3 baseados em TON quando fizer sentido. Para comprar bens e serviços digitais dentro do Telegram, é preciso usar Telegram Stars, não TON.
• Adicione pagamentos com Telegram Stars para bens e serviços digitais, com confirmação adequada dos pagamentos e processamento de reembolsos.
• Salve os dados dos usuários em um servidor depois de validar o initData e conferir todos os valores enviados.
• Adicione animações e lógica avançada.
• Adicione notificações do bot com a permissão necessária do usuário. Um Mini App não pode enviar mensagens para qualquer pessoa.
• Adicione um botão de menu para facilitar a navegação.

E agora?

1. Publique seu app em um servidor HTTPS.
2. Conecte seu app ao Telegram pelo @BotFather.
3. Depure e teste em condições reais.
4. Lance seu Mini App do Telegram e comece a coletar feedback.
5. Compartilhe seu código no GitHub para receber feedback da comunidade, sem incluir tokens do bot, segredos ou dados pessoais.
6. Colete feedback dos usuários e faça melhorias.

Seguindo estas etapas, você estará no caminho certo para criar um Mini App de sucesso no Telegram e aproveitar todo o potencial do ecossistema da plataforma, que não para de crescer.