Servidor de teste do Telegram: como testar um bot no ambiente de teste
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:
- Crie um bot novo com
/newbotno @BotFather (veja como criar um bot no Telegram). - Coloque o token dele na configuração da sua instância de teste, por exemplo em um arquivo
.envseparado. - 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ção | Servidor de teste | |
|---|---|---|
| Conta de usuário | Sua conta normal do Telegram | Uma conta nova criada no ambiente de teste |
| Bots e tokens | Criados no @BotFather em produção | Criados 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 Login | Somente HTTPS | HTTP sem TLS permitido |
| Limites de flood | Limites padrão | Não são ampliados; às vezes podem ser mais rígidos |
| Widgets (Bot API 10.4) | Só no chat privado com o bot | També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:
- iOS: toque 10 vezes no ícone de Configurações → Accounts → Login to another account → Test.
- Telegram Desktop: abra ☰ Configurações, segure Shift+Alt e clique com o botão direito em "Adicionar conta"; depois escolha "Test Server".
- macOS: clique 10 vezes no ícone de Configurações para abrir o Debug Menu, depois ⌘+clique em "Adicionar conta" e faça login com o número de telefone.
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:
- Abra o getMe no Bot API Tester.
- Ative a chave TEST ao lado do campo do token ou abra a página do tester com
?env=testno endereço. - 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
- Não faça teste de carga lá. Os limites de flood não são ampliados no ambiente de teste e às vezes podem ser mais rígidos. Trate o
429comretry_aftere não dependa de valores de limite fixos no código; a lista de métodos e parâmetros está na referência de métodos da Bot API. - Separe os ambientes na configuração. Use variáveis diferentes para o token e para a URL base, e registre no log em qual ambiente o bot foi iniciado.
- Teste de novo em produção. Antes de publicar, rode os mesmos cenários com um bot de teste de produção sobre HTTPS, porque links HTTP e recursos exclusivos do ambiente de teste não vão funcionar para os usuários reais.
Solução de problemas
| Sintoma | Causa provável | Solução |
|---|---|---|
401 Unauthorized | Token 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 found | O chat id veio da produção; esses usuários e chats não existem no servidor de teste | Mande uma mensagem para o bot de teste pela conta de teste e pegue o chat id no getUpdates |
| O bot não aparece na busca | Você está buscando pela conta de produção | Busque pela conta de teste, onde o bot foi criado |
429 Too Many Requests | Limites de flood, que não são ampliados no servidor de teste | Espere retry_after segundos e diminua o ritmo |
| A Mini App via HTTP não abre | O bot ou a conta estão em produção | Use 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á.
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 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.