Como testar uma Mini App do Telegram: do mock no navegador ao app real
Para testar uma Mini App do Telegram, comece num navegador comum com um Telegram.WebApp simulado, depois sirva o build local via HTTPS, registre a URL no @BotFather e abra o app dentro do Telegram com o DevTools conectado. A última etapa acontece no servidor: valide o initData antes de confiar no usuário. Abaixo está o fluxo completo, do localhost ao checklist de produção.
Passo 1: teste a interface num navegador comum
Fora do Telegram não existe cliente por trás do Telegram.WebApp: nada de dados de inicialização, tema ou botões nativos. Mesmo assim, dá para construir boa parte da interface no navegador do desktop, desde que o código tolere essa situação:
const tg = window.Telegram?.WebApp;
const insideTelegram = Boolean(tg?.initData);
if (insideTelegram) {
tg.ready(); // esconde o placeholder de carregamento o quanto antes
tg.expand();
} else {
console.info("Fora do Telegram: usando dados mock");
}
Estilize a página com as variáveis de tema e um valor padrão, por exemplo var(--tg-theme-bg-color, #fff), para que ela fique legível nos dois ambientes.
Para ver o que cada chamada da API faz sem escrever código, abra o Mini App Tester. Num navegador comum ele roda em modo mock e emula o Telegram.WebApp: aperte o MainButton e o BackButton, abra popups, grave no CloudStorage, troque o tema e acompanhe mais de 45 eventos no log. Mas lembre que dados mock são só um substituto: o initData deles não é assinado pelo Telegram e vai (corretamente) falhar na validação do servidor.
Passo 2: rode a Mini App do Telegram a partir do localhost via HTTPS
O Telegram só abre Mini Apps de URLs HTTPS (a exceção é o ambiente de testes), e o seu celular não alcança http://localhost de qualquer forma. O jeito padrão de testar uma Mini App do Telegram em localhost é um túnel que dá ao servidor de desenvolvimento um endereço HTTPS público:
# inicie o servidor de desenvolvimento, por exemplo Vite na porta 5173
npm run dev
# em outro terminal, use um dos túneis
ngrok http 5173
cloudflared tunnel --url http://localhost:5173
Cada ferramenta mostra uma URL pública https://. Dois problemas comuns:
- O Vite recusa o host do túnel. Versões recentes do Vite bloqueiam hosts desconhecidos no servidor de desenvolvimento; adicione o domínio do túnel em
server.allowedHostsnovite.config.js. - O endereço muda. Muitos túneis geram uma URL aleatória nova a cada reinício. Quando isso acontecer, atualize-a no @BotFather ou repita a chamada
setChatMenuButtondo Passo 3.
Passo 3: registre a Mini App no @BotFather
Toda Mini App pertence a um bot. Se você ainda não tem um, veja como criar um bot no Telegram. Depois escolha como os usuários vão abrir a sua URL:
- Link direto: envie
/newapppara o @BotFather, escolha o bot e siga as instruções. O app passa a abrir emhttps://t.me/<bot_username>/<app_name>. - Botão de menu: no @BotFather use
/setmenubuttonou Bot Settings → Menu Button, ou chame o métodosetChatMenuButton. - Botões de teclado: um botão
web_appnum reply keyboard ou num inline keyboard (só em chats privados).
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setChatMenuButton" \
-H "Content-Type: application/json" \
-d '{"menu_button": {"type": "web_app", "text": "Abrir app",
"web_app": {"url": "https://your-tunnel.example.com"}}}'
Sem chat_id, isso define o botão de menu padrão para todos os usuários. Sempre que a URL do túnel mudar, repita a chamada no setChatMenuButton do Bot API Tester em vez de redigitar o curl.
Passo 4: use o ambiente de testes do Telegram
O Telegram mantém um ambiente de testes separado, onde links de Mini App podem usar HTTP puro sem TLS — prático para testar numa rede local. Ele exige uma conta própria e um bot próprio:
- iOS: toque 10 vezes no ícone de Configurações → Accounts → Login to another account → Test.
- Telegram Desktop: ☰ Configurações → Shift+Alt+clique direito em "Add Account" → Test Server.
- macOS: clique 10 vezes no ícone de Configurações para abrir o Debug Menu e depois ⌘+clique em "Add Account".
Crie um bot com o @BotFather dentro da conta de testes e envie as chamadas para https://api.telegram.org/bot<token>/test/METHOD_NAME. Os limites de flood não são maiores lá e podem até ser mais rígidos, então não é lugar para teste de carga. A configuração completa, incluindo a chave TEST do nosso Bot API Tester, está em como usar o servidor de testes do Telegram.
Passo 5: depure a Mini App dentro do Telegram
Muitos bugs que nunca aparecem no Chrome só surgem na WebView real. As instruções oficiais de Debug Mode for Mini Apps, resumidas:
| Plataforma | Como inspecionar |
|---|---|
| iOS | Toque 10 vezes no ícone de Configurações e ative Allow Web View Inspection; conecte via USB e abra Develop → seu dispositivo no Safari de um Mac. |
| Android | Ative a depuração USB; nas Configurações do Telegram role até o fim, mantenha pressionado o número da versão duas vezes e escolha Enable WebView Debug; abra chrome://inspect/#devices no Chrome. |
| Telegram Desktop (Windows, Linux) | Instale a versão beta; Configurações → Avançado → Configurações experimentais → Enable webview inspection; clique direito → Inspect. |
| Telegram para macOS | Instale a versão beta; clique 5 vezes no ícone de Configurações e ative Debug Mini Apps; clique direito → Inspect Element. |
Para comparar clientes rapidamente, defina https://telegram-bot-api.info/telegram-mini-app-tester.html como URL da Mini App de um bot de testes. Dentro do Telegram, o Mini App Tester usa a API real e mostra version, platform, colorScheme, themeParams, safe areas e cada evento que aquele cliente dispara. No seu código, condicione recursos novos com Telegram.WebApp.isVersionAtLeast("8.0") em vez de supor que todo mundo usa a versão mais recente do app.
Passo 6: valide o initData no servidor
Telegram.WebApp.initDataUnsafe serve só para exibição. Envie a string bruta Telegram.WebApp.initData ao backend e verifique-a:
- Faça o parse da query string e remova o
hash. - Ordene os campos restantes em ordem alfabética e junte-os como linhas
key=valueseparadas por\n: essa é adata_check_string. - Calcule
secret_key = HMAC_SHA256(key="WebAppData", message=bot_token). - Os dados são legítimos se
hex(HMAC_SHA256(key=secret_key, message=data_check_string))for igual aohash. - Rejeite dados antigos conferindo o
auth_date.
import crypto from "node:crypto";
export function validateInitData(initData, botToken, maxAgeSec = 3600) {
const params = new URLSearchParams(initData);
const hash = params.get("hash") ?? "";
params.delete("hash");
const dataCheckString = [...params.keys()].sort()
.map((key) => `${key}=${params.get(key)}`)
.join("\n");
const secretKey = crypto.createHmac("sha256", "WebAppData").update(botToken).digest();
const expected = crypto.createHmac("sha256", secretKey).update(dataCheckString).digest("hex");
const valid = hash.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(expected));
const age = Date.now() / 1000 - Number(params.get("auth_date"));
if (!valid || !(age <= maxAgeSec)) return null;
return { ...Object.fromEntries(params), user: JSON.parse(params.get("user") ?? "null") };
}
No cliente, envie a string sem alterações, por exemplo fetch("/api/session", { method: "POST", body: Telegram.WebApp.initData }), e valide com o token do bot que abriu o app. Um terceiro que não pode conhecer o seu token pode verificar o campo signature com a chave pública Ed25519 do Telegram, como descrito na documentação oficial.
Bot API 10.2: proteção de origem das Mini Apps
O Bot API 10.2 proibiu chamar métodos de Mini App a partir de origens diferentes do domínio original da Mini App, e a proteção foi ativada para todas as Mini Apps em 20 de julho de 2026. Nos testes, isso aparece quando o app redireciona da URL registrada do túnel para outro host, como um domínio de staging ou uma página de login: lá as chamadas do Telegram.WebApp deixam de funcionar. Mantenha o código que conversa com o Telegram no domínio registrado e registre a URL de novo sempre que o host do túnel mudar. Dá para desativar a proteção na Mini App pelo @BotFather, mas aí fica por sua conta garantir que a Mini App não tenha links para sites não confiáveis.
Checklist para testar Mini App do Telegram
- A interface funciona em modo mock e nos temas claro e escuro.
Telegram.WebApp.ready()é chamado assim que a interface essencial é renderizada.- A URL no @BotFather ou no
setChatMenuButtoncorresponde ao túnel atual ou ao domínio de produção. - Testado no iOS, Android e desktop com DevTools; recursos novos condicionados com
isVersionAtLeast(). - Layouts em tela cheia respeitam
safeAreaInsetecontentSafeAreaInset. - O backend valida o
initData(hash eauth_date) e nunca confia noinitDataUnsafe. - Todas as chamadas do
Telegram.WebApprodam na origem registrada. - A produção roda no seu próprio domínio com certificado válido, não num túnel temporário.
O código de validação depende do token do bot, então guarde-o em segredo: veja como pegar e proteger o token do bot. Se o mesmo backend também recebe os updates do bot, continue com como configurar o webhook do bot do Telegram. Se você só precisa de um pequeno bloco interativo dentro de uma mensagem do chat, e não de um web app completo, conheça os widgets do Telegram, adicionados no Bot API 10.4.
Perguntas frequentes
Como testar uma Mini App do Telegram em localhost?
O Telegram só abre Mini Apps a partir de URLs HTTPS, então exponha o servidor de desenvolvimento com um túnel HTTPS (ngrok ou Cloudflare Tunnel, por exemplo) e registre essa URL no @BotFather ou com setChatMenuButton. No ambiente de testes, links HTTP sem TLS são permitidos.
Dá para testar uma Mini App sem o Telegram?
Em parte. Um navegador comum não tem o cliente do Telegram por trás, então você precisa de um mock de Telegram.WebApp, como o modo mock do Mini App Tester. O initData real, os popups nativos e a vibração só funcionam dentro do Telegram.
Como abrir o DevTools numa Mini App do Telegram?
No iOS, ative Allow Web View Inspection (toque 10 vezes em Configurações) e use o menu Develop do Safari. No Android, ative WebView Debug nas configurações de debug do Telegram e abra chrome://inspect/#devices. No desktop e no macOS, use as opções de inspeção de webview das versões beta.
Por que a validação do initData falha?
Causas comuns: validar initDataUnsafe em vez da string bruta initData, usar o token de outro bot, não decodificar os valores da URL, deixar o hash na data-check string, inverter chave e mensagem no HMAC ou testar com dados mock que o Telegram nunca assinou.
Por que os métodos do Telegram.WebApp param de funcionar em outro domínio?
Desde o Bot API 10.2, os métodos de Mini App são bloqueados quando chamados de uma origem diferente do domínio da Mini App; a proteção foi ativada para todas as Mini Apps em 20 de julho de 2026. Mantenha o app no domínio registrado ou desative a proteção no @BotFather.
Existe um servidor de testes separado para Mini Apps?
Sim. O ambiente de testes é separado da produção: você precisa de uma conta e de um bot novos lá, as chamadas do Bot API vão para https://api.telegram.org/bot<token>/test/METHOD_NAME e os links de Mini App podem usar HTTP sem TLS.
Guias relacionados
Como criar um bot no Telegram grátis: do BotFather à primeira mensagem
Aprenda a criar bot no Telegram grátis com o @BotFather: pegue o token, teste com getMe e envie a primeira mensagem com curl e Python.
Como hospedar um bot do Telegram: deploy em VPS, Docker e serverless
Como hospedar e fazer deploy de um bot do Telegram: polling ou webhook, serviço systemd na VPS, Docker, Cloudflare Workers com secret_token e checklist.
Telegram Bot API 10.0–10.5: configurações do bot, widgets, rich messages, mensagens efêmeras, guest mode e mais
Novidades do Telegram Bot API 10.0–10.5: setMySettings e BotFullInfo, widgets HTML, rich messages, mensagens efêmeras e guest mode, com exemplos JSON.
Erros do Telegram Bot API: o que cada erro significa e como resolver
Erros do Telegram Bot API explicados: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Causas, soluções e código pronto.
Limites do Telegram Bot API: rate limit, erro 429, tamanho de arquivos e de mensagens
Rate limit do Telegram Bot API na prática: 30 msg/s, 1 msg/s por chat, 20/min em grupos, como tratar 429 e retry_after, limites de arquivo e de texto.
Comandos de bot no Telegram: setMyCommands, escopos e deep links com /start
Configure os comandos do bot do Telegram: /setcommands no @BotFather, setMyCommands com escopos e idiomas, parâmetro do /start e /cmd@bot em grupos.
Teclados de bot no Telegram: inline keyboard, botões de callback e reply keyboard
Botões no bot do Telegram: inline keyboard com callback_data, answerCallbackQuery, editar a mensagem após o clique, reply keyboard e ForceReply.
Integração n8n + Telegram: conecte o bot, dispare workflows e envie mensagens
Conecte o n8n ao Telegram: token do bot como Access Token, webhook do Telegram Trigger com HTTPS público, envio por chat id e soluções para erros comuns.
Como enviar mensagens pela API do Telegram com sendMessage (curl, Python e JavaScript)
Use a API do Telegram para enviar mensagens com sendMessage: exemplos em curl, Python e JavaScript, HTML e MarkdownV2, botões inline e erros comuns.
Telegram bot token: como pegar o token do bot, verificar e revogar
Veja como pegar o token do bot do Telegram no @BotFather, achar o token de um bot existente, testar com getMe e revogar um token vazado.
Como configurar o webhook do bot do Telegram: setWebhook, secret_token e n8n
Configure o webhook do bot do Telegram: requisitos de HTTPS e portas, setWebhook com secret_token, getWebhookInfo, deleteWebhook e erros comuns no n8n.
Chat id do Telegram: como pegar o ID de usuário, grupo, canal e tópico com o seu bot
Descubra o chat id do Telegram para o seu bot: getUpdates em chat privado, grupos, supergrupos (-100), canais e tópicos, e o que fazer se vier vazio.
Bot inline no Telegram: como ativar o modo inline e responder às consultas
Crie um bot inline no Telegram: ative o modo inline no @BotFather ou com setMySettings, trate updates inline_query e responda com answerInlineQuery.
Pagamentos com Telegram Stars em bots: faturas, pre-checkout, reembolsos e assinaturas
Receba pagamentos em Telegram Stars no seu bot: sendInvoice com XTR, pre_checkout_query, successful_payment, reembolsos e assinaturas, com código.
Servidor de teste do Telegram: como testar um bot no ambiente de teste
Use o servidor de teste do Telegram: entre no ambiente de teste, crie um bot de teste, chame a Bot API via /test/ e ative o modo TEST no nosso tester.
Widgets do Telegram para site: login com Telegram, post incorporado, comentários e botão compartilhar
Telegram no seu site: novo login com Telegram (OIDC), Login Widget clássico com checagem do hash, post incorporado, comentários e botão compartilhar.
API JavaScript TelegramWidget: referência, eventos, códigos de erro e limites
Referência da API JavaScript TelegramWidget: propriedades, request(), eventos, códigos de erro, variáveis CSS, widget_query, answerWidgetQuery e limites.
Exemplos de widget do Telegram: HTML completo e bot em Python
Exemplos de widget do Telegram com código completo: card de pedido, contador com widget_query, enquete compartilhada ao vivo e prévia no navegador.
Widgets do Telegram: blocos HTML interativos dentro das mensagens do bot
Widgets do Telegram (Bot API 10.4): o que são, como funcionam sendWidget, chat_data e public_data, onde já rodam e a diferença para Mini Apps.