Telegram Bot API

Como testar uma Mini App do Telegram: do mock no navegador ao app real

· 7 min de leitura

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:

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:

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:

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:

PlataformaComo inspecionar
iOSToque 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.
AndroidAtive 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 macOSInstale 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:

  1. Faça o parse da query string e remova o hash.
  2. Ordene os campos restantes em ordem alfabética e junte-os como linhas key=value separadas por \n: essa é a data_check_string.
  3. Calcule secret_key = HMAC_SHA256(key="WebAppData", message=bot_token).
  4. Os dados são legítimos se hex(HMAC_SHA256(key=secret_key, message=data_check_string)) for igual ao hash.
  5. 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

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.

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.