Cómo alojar un bot de pyTelegramBotAPI 24/7

Para alojar un bot de pyTelegramBotAPI (telebot) 24/7, ejecútalo en una máquina que siga encendida en lugar de tu PC: un VPS Linux con un servicio de systemd que lo arranque de nuevo tras un fallo o un reinicio, o un plan de bots de PlayNHost (desde US$1.99 al mes, consulta alojamiento de bots de Telegram), donde subes tu código, pegas el token y pulsas Iniciar. En nuestra prueba, un bot con pyTelegramBotAPI 4.37.1 usó unos 40 MB de memoria en reposo; nuestro plan de bots más pequeño, STARTER, tiene 0.5 GB. Ambas vías usan long polling: bot.infinity_polling() pide a Telegram los mensajes nuevos, así que el bot no necesita una dirección pública. Los pasos en PlayNHost:

1. En Telegram, envía /newbot a @BotFather y copia el token que te da.
2. En alojamiento de bots de Telegram, haz clic en Crear servidor en un plan. En la ventana del pedido, responde a ¿Para qué plataforma es tu bot? con Telegram y elige Python.
3. Abre tu servidor en el panel. La tarjeta Configura tu bot en Resumen se abre en Conectar con Telegram; su primer paso, Qué se ejecuta, debería decir Este bot ejecuta Python Bot.
4. En Conectar con Telegram, pega el token y haz clic en Conexión. Comprueba el nombre del bot que aparece y haz clic en Sí, continuar.
5. En Tu código, haz clic en Subir archivos para abrir Files y sube bot.py y requirements.txt, o haz clic en Conectar Git. En requirements.txt el paquete es pyTelegramBotAPI, no telebot.
6. En la página Bot, panel Código, comprueba que Archivo de entrada sea el archivo que llama a infinity_polling() (bot.py por defecto) y que Entorno de ejecución sea Python 3.11 o más reciente.
7. Haz clic en Iniciar bot, abre Console y espera a Logged in as @your_bot. El indicador en Resumen cambia a En línea en Telegram. Envía /start a tu bot.

El primer arranque tarda más mientras pip instala pyTelegramBotAPI. Después solo vuelve a instalar cuando cambian tu archivo de requisitos, los paquetes adicionales o la versión de Python, o una vez al día. Paso a paso con capturas: Cómo alojar un bot de Telegram.

Qué medimos

Ejecutamos las tres bibliotecas de Telegram para Python en uno de nuestros propios servidores, en contenedores desechables configurados como el panel ejecuta un bot de Python: Python 3.12 (el Entorno de ejecución marcado como recomendado), paquetes instalados con el mismo comando de pip, un límite de memoria de 1 GB y un núcleo de CPU.

Cada bot cargó la biblioteca y preguntó a Telegram quién es con un token falso (pyTelegramBotAPI: bot.get_me() en el TeleBot simple). La memoria es la que ocupaban los procesos del bot 15 segundos después de que Telegram rechazara el token; el tiempo de arranque va desde el lanzamiento de Python hasta que la biblioteca informa de esa respuesta, así que incluye un viaje de ida y vuelta a Telegram. Ambos datos son la mediana de tres ejecuciones tras una ejecución de calentamiento.

Estas cifras son el mínimo de la biblioteca: sin chats, sin manejadores trabajando, sin nada en caché. Tu propio código, los datos que guarda en memoria y el número de chats que atiende se suman a eso, así que elige el plan según lo que haga tu bot. El tamaño instalado incluye las dos bibliotecas HTTP de las que depende pyTelegramBotAPI, requests y aiohttp, aunque uses solo el TeleBot simple.

Un bot mínimo de pyTelegramBotAPI

Responde a /start, lee el token que le da el panel e imprime una línea de listo. Pon la biblioteca en requirements.txt:

pyTelegramBotAPI>=4,<5

Y el código en bot.py:

import os

import telebot

bot = telebot.TeleBot(os.environ["TELEGRAM_BOT_TOKEN"])


@bot.message_handler(commands=["start"])
def start(message):
    bot.reply_to(message, "Hello! I am running on PlayNHost.")


bot.delete_webhook()
print(f"Logged in as @{bot.user.username}")
bot.infinity_polling()

Las dos llamadas antes del polling importan en un host. delete_webhook() elimina un webhook que quedó de otro host, y bot.user pregunta a Telegram quién es el bot, de modo que Logged in as @your_bot aparece solo con un token que Telegram acepta. El panel lee esa línea para mostrar En línea en Telegram. Ambas llamadas también detienen el bot al instante con un error claro cuando el token es incorrecto, en lugar de dejar que el polling lo reintente en segundo plano. El panel entrega el token a tu código como TELEGRAM_BOT_TOKEN, y también como BOT_TOKEN, TOKEN y TELEGRAM_TOKEN.

Si el token es incorrecto

En nuestra prueba, con un token que Telegram rechaza, nuestro bot de prueba imprimió:

ApiTelegramException: A request to the Telegram API was unsuccessful. Error code: 401. Description: Unauthorized

En un traceback completo la clase aparece como telebot.apihelper.ApiTelegramException. Con el bot de arriba, la primera llamada falla y el bot se detiene con código de salida 1; en PlayNHost el panel muestra Telegram no aceptó el token de tu bot sobre la consola, con Reemplazar el token. Para solucionarlo, copia el token de nuevo: en @BotFather envía /mybots, elige tu bot y luego API Token. Pégalo en la página Bot, panel Telegram, en Token, y vuelve a iniciar el bot.

Un bot que llama a infinity_polling() directamente, como hacen la mayoría de los ejemplos, se comporta de otra manera: no se detiene. El polling primero pregunta a Telegram quién es el bot; con un token rechazado eso falla, y el bot registra Infinity polling exception: A request to the Telegram API was unsuccessful. Error code: 401. Description: Unauthorized y lo reintenta cada 3 segundos mientras el proceso siga en marcha. Un token revocado cuando el bot ya está haciendo polling da Threaded polling exception: con el mismo mensaje, reintentado tras una espera que se duplica cada vez, hasta un minuto. En ambos casos el bot parece estar en marcha mientras nada responde. El panel reconoce ambas líneas y muestra el mismo aviso.

Lo que un host debe saber sobre pyTelegramBotAPI

• Nombres del paquete y de la importación: instalas pyTelegramBotAPI e importas telebot. El paquete de PyPI llamado telebot es un proyecto distinto y pequeño; pon pyTelegramBotAPI en requirements.txt.
• Versión de Python: pyTelegramBotAPI 4.37.1 necesita Python 3.11 o más reciente. En Python 3.10, pip no falla: instala 4.37.0, la última versión que admitía 3.10. Mantén Entorno de ejecución en el panel Código en 3.11 o más reciente (3.12 está marcado como recomendado) para obtener la versión actual.
• infinity_polling() o polling(): usa infinity_polling(). El polling() simple se detiene en el primer error de Telegram, y una excepción en uno de tus manejadores también lo termina, así que el bot sale. Con infinity_polling(), los errores de Telegram se reintentan, y cualquier otra excepción en un manejador se registra como Infinity polling exception: ... antes de que el polling vuelva a empezar 3 segundos después.
• Logging: pyTelegramBotAPI tiene su propio logger, TeleBot, configurado en ERROR, así que no imprime nada al arrancar; por eso el bot de arriba imprime su propia línea de listo. Los errores aparecen en una línea sin el traceback. Para ver dónde falló un manejador, arranca con bot.infinity_polling(logger_level=logging.DEBUG) (y import logging), que añade el traceback. Estas líneas ocultan la parte secreta de tu token.
• Un webhook que quedó de otro host: el polling no lo elimina, y Telegram rechaza el polling mientras haya uno configurado. Mantén bot.delete_webhook() como arriba, o haz clic en Quitar webhook en la página Bot, panel Telegram.
• Hilos o asyncio: TeleBot usa requests y ejecuta los manejadores en dos hilos de trabajo por defecto (num_threads=2); un manejador lento retiene uno de ellos. AsyncTeleBot de telebot.async_telebot usa aiohttp y se ejecuta con asyncio.run(bot.polling()). Ambos funcionan igual en el panel.
• Una segunda copia: cuando otra copia hace polling con el mismo token, Telegram responde 409 Conflict e infinity_polling() reintenta mientras siga en marcha. El panel muestra Tu bot también se está ejecutando en otro sitio. Consulta Solucionar el error 409 Conflict de un bot de Telegram.

Alójalo tú mismo en un VPS Linux

En Debian o Ubuntu, instala Python, crea un usuario para el bot e instala la biblioteca en un entorno virtual. Comprueba antes python3 --version: por debajo de 3.11, pip instala un pyTelegramBotAPI más antiguo.

sudo apt update
sudo apt install -y python3 python3-venv
sudo useradd --system --create-home --home-dir /opt/tgbot --shell /usr/sbin/nologin tgbot
sudo cp bot.py requirements.txt /opt/tgbot/
sudo -u tgbot python3 -m venv /opt/tgbot/venv
sudo -u tgbot /opt/tgbot/venv/bin/pip install -r /opt/tgbot/requirements.txt

Guarda el token en un archivo que solo root pueda leer. Ábrelo con sudo nano /etc/tgbot.env, escribe una línea, guarda y luego ejecuta sudo chmod 600 /etc/tgbot.env:

TELEGRAM_BOT_TOKEN=123456789:your-token-from-botfather

Crea /etc/systemd/system/tgbot.service:

[Unit]
Description=Telegram bot (pyTelegramBotAPI)
Wants=network-online.target
After=network-online.target

[Service]
User=tgbot
WorkingDirectory=/opt/tgbot
EnvironmentFile=/etc/tgbot.env
Environment=PYTHONUNBUFFERED=1
ExecStart=/opt/tgbot/venv/bin/python /opt/tgbot/bot.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Arráncalo ahora y en cada inicio del sistema, y luego sigue su salida:

sudo systemctl daemon-reload
sudo systemctl enable --now tgbot
sudo journalctl -u tgbot -f

PYTHONUNBUFFERED=1 importa aquí: cuando la salida de Python no va a un terminal, se almacena en bloques en un búfer, así que sin esa variable Logged in as puede quedarse en un búfer en lugar de llegar al journal. Restart=always también vuelve a iniciar el bot 5 segundos después de que se detenga por un token incorrecto, así que revisa el journal si no deja de reiniciarse. Tras cambiar el código, ejecuta sudo systemctl restart tgbot. Detén antes cualquier copia en tu PC, o Telegram responderá 409 Conflict.

Autoalojamiento o plan de bots

• En un VPS que gestionas tú: las actualizaciones del sistema, la versión de Python, el entorno virtual, la reinstalación de paquetes, el archivo de unidad, la lectura del journal y darte cuenta de cuándo el bot deja de responder. A cambio tienes root y puedes ejecutar un webhook si añades un dominio y HTTPS.
• En un plan de bots el panel se encarga de: instalar requirements.txt cuando cambia, volver a iniciar el bot tras un fallo, comprobar el token con Telegram antes de guardarlo, dárselo a tu código con cinco nombres, leer la consola y nombrar la causa cuando el bot deja de responder (un token rechazado, una segunda copia, un webhook), con un botón para el token y el webhook. Nuestros planes de bots aún no incluyen una dirección HTTPS pública, así que los bots allí usan long polling, que es lo que hace infinity_polling().

Preguntas frecuentes

¿Por qué mi bot de telebot funciona pero nunca responde?

Porque infinity_polling() reintenta cada error de Telegram sin detenerse: un token rechazado, otra copia usando el mismo token, un webhook que quedó en el bot. Busca líneas con Infinity polling exception (un token rechazado al arrancar) o Threaded polling exception (una vez que el polling funciona) en la Console; el panel convierte cada una de las tres causas en un aviso que la nombra.

Me sale ModuleNotFoundError: No module named 'telebot'. ¿Qué falta?

El paquete. Añade pyTelegramBotAPI a requirements.txt y vuelve a iniciar el bot: el archivo de requisitos cambió, así que pip lo instala en ese arranque. La importación sigue siendo import telebot.

¿Necesita pyTelegramBotAPI un webhook para seguir en línea?

No. infinity_polling() sigue pidiendo mensajes nuevos a Telegram, así que el bot responde mientras el proceso esté en marcha. Para mover un bot que usaba un webhook: Cómo mover un bot de Telegram a PlayNHost.

¿Debo usar TeleBot o AsyncTeleBot?

Cualquiera funciona en un plan de bots. Usa el que use tu código o tu tutorial: con TeleBot los manejadores son funciones normales, con AsyncTeleBot son funciones async def que hacen await a los métodos del bot. Nuestra medición de arriba es para el TeleBot simple.

pyTelegramBotAPI funciona en todos los planes de bots de PlayNHost, desde STARTER (0.5 GB). Compara los planes y haz clic en Crear servidor en alojamiento de bots de Telegram.