Telegram Bot API

Servidor de teste do Telegram: como testar um bot no ambiente de teste

· 7 min de leitura

O servidor de teste do Telegram é um ambiente de teste separado, com contas e bots próprios, em que o seu bot chama a Bot API em https://api.telegram.org/bot<token>/test/METHOD_NAME. Ele é útil quando você precisa de links HTTP simples para Mini Apps ou Web Login, de usuários de teste descartáveis ou de recursos da Bot API que, por enquanto, só estão liberados lá. Para os testes do dia a dia, muitas vezes basta um segundo bot em produção. Este guia mostra as duas opções, como entrar no ambiente de teste no iOS, no Desktop e no macOS e como chamar a API de teste com curl, Python, JavaScript e o nosso Bot API Tester.

Opção 1: um bot de teste separado em produção

O jeito mais rápido de testar um bot do Telegram sem atrapalhar os usuários é rodar uma segunda instância do seu código em outra conta de bot:

  1. Crie um bot novo com /newbot no @BotFather (veja como criar um bot no Telegram).
  2. Coloque o token dele na configuração da sua instância de teste, por exemplo em um arquivo .env separado.
  3. Depure à vontade com o bot novo; o bot de produção continua rodando sem nenhuma alteração.

Um detalhe importante: o file_id fica vinculado a um único id de bot. O bot de teste não consegue reaproveitar os valores de file_id salvos pelo bot principal, então as mídias precisam ser enviadas de novo pelo bot de teste.

Opção 2: o ambiente de teste dedicado do Telegram

O Telegram também mantém um ambiente de teste dedicado para testes mais avançados. Ele é totalmente separado do ambiente principal (produção): contas, bots, chats e tokens de produção não existem lá. Veja o que muda:

ProduçãoServidor de teste
Conta de usuárioSua conta normal do TelegramUma conta nova criada no ambiente de teste
Bots e tokensCriados no @BotFather em produçãoCriados no @BotFather dentro da conta de teste; tokens separados
URL da Bot API/bot<token>/METHOD_NAME/bot<token>/test/METHOD_NAME
Links de Mini App e Web LoginSomente HTTPSHTTP sem TLS permitido
Limites de floodLimites padrãoNão são ampliados; às vezes podem ser mais rígidos
Widgets (Bot API 10.4)Só no chat privado com o botTambém em grupos, modo inline e encaminhamentos

Crie uma conta de teste no iOS, Desktop ou macOS

Entre no ambiente de teste do Telegram por um aplicativo oficial:

A conta de teste fica ao lado da sua conta normal, então dá para alternar entre os ambientes no mesmo aplicativo. Tudo o que você fizer lá, incluindo as conversas com o bot de teste, fica restrito ao ambiente de teste.

Crie um bot no servidor de teste e pegue o token

Na conta de teste, abra o @BotFather e crie o bot do jeito de sempre: /newbot, um nome de exibição e um username terminado em bot. O BotFather responde com um token do ambiente de teste. Ele tem a mesma cara de qualquer outro token, mas só funciona com a URL /test/ da API. Guarde-o com um nome separado, por exemplo TEST_BOT_TOKEN, para nunca confundi-lo com o de produção; as recomendações do guia sobre o token do bot também valem aqui.

Chame a Bot API no servidor de teste do Telegram

Todos os métodos da Bot API funcionam igual; a única diferença é o /test/ depois do token. Confira o token com getMe:

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/getMe"

No código, mantenha a URL base em uma única constante: assim, trocar de ambiente é questão de mudar uma linha. Este bot de eco mínimo confere o token, recebe updates com long polling via getUpdates e, ao receber 429, espera o tempo indicado em retry_after:

import os
import time
import requests

TOKEN = os.environ["TEST_BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}/test"  # remova "/test" para produção


def call(method, **params):
    while True:
        data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
        if data["ok"]:
            return data["result"]
        if data.get("error_code") == 429:  # limite de flood: espere o tempo indicado
            time.sleep(data["parameters"]["retry_after"])
            continue
        raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")


me = call("getMe")
print("Rodando no servidor de teste como @" + me["username"])

offset = 0
while True:
    for update in call("getUpdates", offset=offset, timeout=30):
        offset = update["update_id"] + 1
        msg = update.get("message")
        if msg and "text" in msg:
            call("sendMessage", chat_id=msg["chat"]["id"], text="Eco de teste: " + msg["text"])
const TOKEN = process.env.TEST_BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}/test`; // remova "/test" para produção

async function call(method, params = {}) {
  while (true) {
    const res = await fetch(`${API}/${method}`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(params),
      signal: AbortSignal.timeout(40_000),
    });
    const data = await res.json();
    if (data.ok) return data.result;
    if (data.error_code === 429) { // limite de flood: espere o tempo indicado
      await new Promise((resolve) => setTimeout(resolve, data.parameters.retry_after * 1000));
      continue;
    }
    throw new Error(`${method}: ${data.error_code} ${data.description}`);
  }
}

const me = await call("getMe");
console.log("Rodando no servidor de teste como @" + me.username);

let offset = 0;
while (true) {
  for (const update of await call("getUpdates", { offset, timeout: 30 })) {
    offset = update.update_id + 1;
    const msg = update.message;
    if (msg?.text) {
      await call("sendMessage", { chat_id: msg.chat.id, text: "Eco de teste: " + msg.text });
    }
  }
}

Mande /start para o bot pela sua conta de teste e ele responde. A versão em JavaScript usa await no nível superior, então salve-a como bot.mjs e rode com Node.js 18 ou mais recente.

Webhooks funcionam da mesma forma: chame setWebhook pela URL de teste, e as regras de sempre para url, portas e secret_token continuam valendo. Confira o resultado com getWebhookInfo, também via /test/:

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/setWebhook" \
  -d "url=https://example.com/telegram/webhook"
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/getWebhookInfo"

As bibliotecas de bots costumam montar as URLs das requisições a partir de um endereço base. Se a sua permitir sobrescrever a URL base da Bot API, configure-a para que as requisições cheguem em …/bot<token>/test/METHOD_NAME; o nome exato da opção muda de uma biblioteca para outra, então consulte a documentação da sua.

Teste o servidor de teste no Bot API Tester

O nosso Bot API Tester envia requisições para o ambiente de teste sem você escrever nenhuma linha de código:

  1. Abra o getMe no Bot API Tester.
  2. Ative a chave TEST ao lado do campo do token ou abra a página do tester com ?env=test no endereço.
  3. Cole o token do seu bot de teste e clique em Execute. Agora as requisições vão para https://api.telegram.org/bot<token>/test/METHOD.

Enquanto a chave estiver ativada, todos os métodos usam a URL de teste, inclusive o long polling do getUpdates, então você vê os updates da sua conta de teste chegando no histórico. O tester lembra a posição da chave no seu navegador; desative-a antes de colar um token de produção. Como sempre, o token fica no localStorage do seu navegador e as requisições vão direto para api.telegram.org.

Mini Apps e Web Login com HTTP simples

Esse é o principal motivo para quem desenvolve Mini Apps usar o ambiente de teste: lá, a url em WebAppInfo (Mini Apps) e em LoginUrl (botões de Web Login) pode ser um link HTTP sem TLS. Assim, você aponta o botão de menu ou um botão web_app do bot de teste para um servidor de desenvolvimento na sua rede local, sem configurar certificados nem túnel. Em produção, os links precisam usar HTTPS. Para testar a API Telegram.WebApp direto no navegador, use o nosso Mini App Tester.

Widgets da Bot API 10.4 no servidor de teste

Os widgets HTML em mensagens, que chegaram na Bot API 10.4, por enquanto só funcionam em produção no chat privado com o bot. Widgets em grupos, no modo inline e em mensagens encaminhadas funcionam, por ora, apenas no servidor de teste, então é lá que dá para testar esses cenários. Veja em widgets do Telegram como eles funcionam.

Limites e boas práticas

Solução de problemas

SintomaCausa provávelSolução
401 UnauthorizedToken de produção enviado para /test/, ou token de teste enviado sem /test/Os ambientes são separados: combine o token com a URL certa (ou com a chave TEST no tester)
400 Bad Request: chat not foundO chat id veio da produção; esses usuários e chats não existem no servidor de testeMande uma mensagem para o bot de teste pela conta de teste e pegue o chat id no getUpdates
O bot não aparece na buscaVocê está buscando pela conta de produçãoBusque pela conta de teste, onde o bot foi criado
429 Too Many RequestsLimites de flood, que não são ampliados no servidor de testeEspere retry_after segundos e diminua o ritmo
A Mini App via HTTP não abreO bot ou a conta estão em produçãoUse um bot criado no ambiente de teste e abra-o pela conta de teste

Perguntas frequentes

O que é o servidor de teste do Telegram?

É um ambiente de teste dedicado, totalmente separado do Telegram de produção. Ele tem contas de usuário e bots próprios, e os bots chamam a Bot API em https://api.telegram.org/bot<token>/test/METHOD_NAME.

Como entrar no ambiente de teste do Telegram?

No iOS, toque 10 vezes no ícone de Configurações → Accounts → Login to another account → Test. No Telegram Desktop, abra ☰ Configurações, segure Shift + Alt e clique com o botão direito em Adicionar conta → Test Server. No macOS, clique 10 vezes no ícone de Configurações para abrir o Debug Menu e depois ⌘ + clique em Adicionar conta.

Posso usar o token do meu bot de produção no servidor de teste?

Não. Os ambientes são separados: um bot criado em produção não existe no servidor de teste, e vice-versa. Crie um bot novo no @BotFather dentro da sua conta de teste; usar o token no ambiente errado normalmente resulta em 401 Unauthorized.

Os limites de requisições são maiores no servidor de teste do Telegram?

Não. Os limites de flood não são ampliados no ambiente de teste e às vezes podem ser até mais rígidos. Trate o 429 Too Many Requests com retry_after e não fixe valores de limite no código.

Uma Mini App pode usar HTTP simples no ambiente de teste?

Sim. No ambiente de teste, a url de WebAppInfo (Mini Apps) e de LoginUrl (Web Login) pode ser um link HTTP sem TLS. Em produção, os links precisam usar HTTPS.

Preciso sempre do servidor de teste para testar um bot?

Não. Na maioria dos casos, um segundo bot criado no @BotFather em produção resolve: ele tem token próprio e não interfere nos seus usuários reais. Use o servidor de teste quando precisar de links HTTP, contas de teste separadas ou recursos disponíveis só lá.

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

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.