Telegram Bot API

Servidor de pruebas de Telegram: cómo probar un bot en el entorno de pruebas

· 7 min de lectura

El servidor de pruebas de Telegram es un entorno de pruebas separado, con sus propias cuentas y bots, donde tu bot llama a la Bot API en https://api.telegram.org/bot<token>/test/METHOD_NAME. Úsalo cuando necesites enlaces HTTP simples para Mini Apps o Web Login, un grupo de usuarios de prueba desechables o funciones de la Bot API que por ahora solo están habilitadas ahí. Para las pruebas del día a día, muchas veces basta con un segundo bot en producción. En esta guía vemos ambas opciones, cómo entrar al entorno de pruebas en iOS, Desktop y macOS, y cómo llamar a la API de pruebas desde curl, Python, JavaScript y nuestro Bot API Tester.

Opción 1: un bot de prueba aparte en producción

La forma más rápida de probar un bot de Telegram sin afectar a sus usuarios es ejecutar una segunda instancia de tu código con otra cuenta de bot:

  1. Crea un bot nuevo con /newbot en @BotFather (consulta cómo crear un bot de Telegram).
  2. Pon su token en la configuración de tu instancia de prueba, por ejemplo en un archivo .env aparte.
  3. Depura en privado con el bot nuevo; el bot de producción sigue funcionando sin cambios.

Un detalle importante: cada file_id está ligado al id de un solo bot. Un bot de prueba no puede reutilizar los valores de file_id guardados por el bot principal, así que el bot de prueba tiene que volver a subir los archivos.

Opción 2: el entorno de pruebas dedicado de Telegram

Telegram también ofrece un entorno de pruebas dedicado para pruebas más avanzadas. Está completamente separado del entorno principal (producción): ahí no existen las cuentas, bots, chats ni tokens de producción. Esto es lo que cambia:

ProducciónServidor de pruebas
Cuenta de usuarioTu cuenta normal de TelegramUna cuenta nueva creada en el entorno de pruebas
Bots y tokensSe crean con @BotFather en producciónSe crean con @BotFather dentro de la cuenta de prueba; tokens separados
URL de la Bot API/bot<token>/METHOD_NAME/bot<token>/test/METHOD_NAME
Enlaces de Mini Apps y Web LoginSolo HTTPSSe permite HTTP sin TLS
Límites de floodLímites estándarNo se elevan; a veces pueden ser más estrictos
Widgets (Bot API 10.4)Solo en el chat privado con el botTambién en grupos, modo inline y reenvíos

Crear una cuenta de prueba en iOS, Desktop o macOS

Entra al entorno de pruebas de Telegram desde una app oficial:

La cuenta de prueba se agrega junto a tu cuenta habitual, así que puedes cambiar de entorno en la misma app. Todo lo que hagas ahí, incluidos los chats con tu bot de prueba, se queda en el entorno de pruebas.

Crear un bot en el servidor de pruebas y obtener su token

Dentro de la cuenta de prueba, abre @BotFather y crea un bot como siempre: /newbot, un nombre visible y después un username que termine en bot. BotFather responde con un token para el entorno de pruebas. Se ve como cualquier otro token, pero solo funciona con la URL de la API que incluye /test/. Guárdalo con un nombre distinto, por ejemplo TEST_BOT_TOKEN, para que nunca se mezcle con el de producción; las reglas de la guía del token del bot también aplican aquí.

Llamar a la Bot API en el servidor de pruebas de Telegram

Todos los métodos de la Bot API funcionan igual; la única diferencia es /test/ después del token. Comprueba el token con getMe:

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

En el código, guarda la URL base en una sola constante para que cambiar de entorno sea cuestión de modificar una línea. Este bot de eco mínimo comprueba el token, recibe actualizaciones con long polling mediante getUpdates y, ante un 429, espera lo que indica retry_after:

import os
import time
import requests

TOKEN = os.environ["TEST_BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}/test"  # quita "/test" para producción


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:  # límite de flood: espera lo indicado
            time.sleep(data["parameters"]["retry_after"])
            continue
        raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")


me = call("getMe")
print("Funcionando en el servidor de pruebas 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 prueba: " + msg["text"])
const TOKEN = process.env.TEST_BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}/test`; // quita "/test" para producción

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) { // límite de flood: espera lo 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("Funcionando en el servidor de pruebas 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 prueba: " + msg.text });
    }
  }
}

Envía /start al bot desde tu cuenta de prueba y te responderá. La versión en JavaScript usa await de nivel superior, así que guárdala como bot.mjs y ejecútala con Node.js 18 o posterior.

Los webhooks funcionan igual: llama a setWebhook a través de la URL de pruebas, y se aplican las reglas habituales sobre url, puertos y secret_token. Revisa el resultado con getWebhookInfo, también a través de /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"

Las librerías para bots suelen armar las URL de las peticiones a partir de una dirección base. Si la tuya permite cambiar la URL base de la Bot API, configúrala para que las peticiones terminen en …/bot<token>/test/METHOD_NAME; el nombre exacto de la opción varía según la librería, así que búscalo en su documentación.

Prueba el servidor de pruebas en Bot API Tester

Nuestro Bot API Tester puede enviar peticiones al entorno de pruebas sin escribir código:

  1. Abre getMe en Bot API Tester.
  2. Activa el interruptor TEST junto al campo del token, o abre la página del tester con ?env=test en la dirección.
  3. Pega el token de tu bot de prueba y presiona Execute. Ahora las peticiones van a https://api.telegram.org/bot<token>/test/METHOD.

Mientras el interruptor está activado, todos los métodos usan la URL de pruebas, incluido el long polling con getUpdates, así que puedes ver en el historial cómo llegan las actualizaciones desde tu cuenta de prueba. El tester recuerda el interruptor en tu navegador; desactívalo antes de pegar un token de producción. Como siempre, el token se queda en el localStorage de tu navegador y las peticiones van directo a api.telegram.org.

Mini Apps y Web Login por HTTP simple

Esta es la razón principal por la que los desarrolladores de Mini Apps usan el entorno de pruebas: ahí la url de WebAppInfo (Mini Apps) y de LoginUrl (botones de Web Login) puede ser un enlace HTTP sin TLS. Así puedes apuntar el botón de menú o un botón web_app de un bot de prueba a un servidor de desarrollo en tu red local sin configurar certificados ni un túnel. En producción los enlaces deben usar HTTPS. Para revisar la parte web de tu Mini App en el navegador, usa nuestro Mini App Tester.

Widgets de Bot API 10.4 en el servidor de pruebas

Los widgets HTML en mensajes, agregados en Bot API 10.4, por ahora funcionan en producción solo en el chat privado con el bot. Los widgets en grupos, en modo inline y en mensajes reenviados funcionan, de momento, únicamente en el servidor de pruebas, así que ahí puedes probar esos escenarios. En la guía de widgets de Telegram explicamos cómo funcionan.

Límites y buenas prácticas

Solución de problemas

SíntomaCausa probableSolución
401 UnauthorizedSe envió un token de producción a /test/, o un token de prueba sin /test/Los entornos están separados: haz coincidir el token con la URL (o con el interruptor TEST del tester)
400 Bad Request: chat not foundEl chat id viene de producción; esos usuarios y chats no existen en el servidor de pruebasEscríbele al bot de prueba desde tu cuenta de prueba y toma el chat id de getUpdates
No encuentras el bot en la búsquedaEstás buscando desde tu cuenta de producciónBusca desde la cuenta de prueba, donde se creó el bot
429 Too Many RequestsLímites de flood, que no se elevan en el servidor de pruebasEspera retry_after segundos y reduce el ritmo
La Mini App por HTTP no se abreEl bot o la cuenta están en producciónUsa un bot creado en el entorno de pruebas y ábrelo desde la cuenta de prueba

Preguntas frecuentes

¿Qué es el servidor de pruebas de Telegram?

Un entorno de pruebas dedicado y totalmente separado del Telegram de producción. Tiene sus propias cuentas de usuario y sus propios bots, y los bots llaman a la Bot API en https://api.telegram.org/bot<token>/test/METHOD_NAME.

¿Cómo entro al entorno de pruebas de Telegram?

En iOS toca 10 veces el ícono de Ajustes → Accounts → Login to another account → Test. En Telegram Desktop abre ☰ Ajustes, mantén Shift + Alt y haz clic derecho en «Agregar cuenta» → Test Server. En macOS haz clic 10 veces en el ícono de Ajustes para abrir el Debug Menu y luego ⌘ + clic en «Agregar cuenta».

¿Puedo usar el token de mi bot de producción en el servidor de pruebas?

No. Los entornos están separados: un bot creado en producción no existe en el servidor de pruebas y viceversa. Crea un bot nuevo con @BotFather dentro de tu cuenta de prueba; usar el token del entorno equivocado suele terminar en 401 Unauthorized.

¿Los límites son más altos en el servidor de pruebas de Telegram?

No. Los límites de flood no se elevan en el entorno de pruebas y a veces pueden ser más estrictos, así que maneja 429 Too Many Requests con retry_after y no fijes valores de límites en el código.

¿Una Mini App puede usar HTTP simple en el entorno de pruebas?

Sí. En el entorno de pruebas la url de WebAppInfo (Mini Apps) y de LoginUrl (Web Login) puede ser un enlace HTTP sin TLS. En producción los enlaces deben usar HTTPS.

¿Siempre necesito el servidor de pruebas para probar un bot?

No. Para la mayoría de los casos basta con un segundo bot creado con @BotFather en producción: tiene su propio token y no molesta a tus usuarios reales. Usa el servidor de pruebas cuando necesites enlaces HTTP, cuentas de prueba separadas o funciones disponibles solo ahí.

Cómo crear un bot en Telegram paso a paso: de BotFather a tu primer mensaje

Aprende a crear un bot de Telegram: /newbot en @BotFather, token, prueba con getMe y tu primer mensaje con curl y Python. Gratis y sin servidor.

Cómo enviar mensajes con la API de Telegram: sendMessage paso a paso

Envía mensajes con la Bot API de Telegram: sendMessage con curl, Python y JavaScript, formato HTML y MarkdownV2, botones inline y errores 400, 403 y 429.

Cómo obtener el token de un bot de Telegram (y qué hacer si se filtra)

Cómo obtener el token de tu bot de Telegram con @BotFather, encontrarlo si el bot ya existe, comprobarlo con getMe y revocarlo si se filtró.

Webhook de Telegram: cómo configurar setWebhook para tu bot (Python y n8n)

Configura el webhook de tu bot de Telegram: requisitos HTTPS, setWebhook con secret_token, getWebhookInfo, handler en Python y errores típicos en n8n.

Cómo obtener el chat id de Telegram: usuarios, grupos, canales y temas

Obtén el chat id de Telegram para tu bot con getUpdates: usuarios, grupos, supergrupos (-100…), canales y temas, y qué hacer si result viene vacío.

Widgets de Telegram para tu sitio web: iniciar sesión con Telegram, posts, comentarios y botón compartir

Integra Telegram en tu sitio: iniciar sesión con Telegram (OIDC), el Login Widget clásico con verificación del hash, posts embebidos y botón compartir.

API JavaScript de TelegramWidget: referencia, eventos, errores y límites

Referencia de la API JavaScript TelegramWidget: propiedades, request(), eventos, errores, variables CSS, widget_query, answerWidgetQuery y límites.

Ejemplos de widgets de Telegram: HTML completo y bot en Python

Ejemplos de widgets de Telegram listos para usar: tarjeta de pedido, contador con widget_query, encuesta compartida en vivo y vista previa en el navegador.

Widgets de Telegram: HTML interactivo dentro de los mensajes de tu bot

Widgets de Telegram (Bot API 10.4): qué son, cómo funcionan sendWidget, chat_data y public_data, dónde se usan hoy y en qué difieren de las Mini Apps.