Cómo alojar un bot de aiogram 24/7 en un plan de bots o un VPS

Para alojar un bot de aiogram 24/7, ejecútalo en una máquina que siga encendida en lugar de en 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 aiogram 3.31.0 usó unos 173 MB de memoria en reposo; nuestro plan de bots más pequeño, STARTER, tiene 0,5 GB. Ambas opciones usan long polling: dp.start_polling(bot) 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 ¿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.
6. En la página Bot, panel Código, comprueba que el Archivo de entrada es el archivo que ejecuta asyncio.run(main()) (bot.py por defecto).
7. Haz clic en Iniciar bot, abre la Console y espera la línea de aiogram Run polling for bot @your_bot. El indicador de Resumen pasa a En línea en Telegram. Envía /start a tu bot.

El primer arranque tarda más mientras pip instala aiogram y sus dependencias. Después solo vuelve a instalar cuando cambian tu archivo de requisitos, los paquetes extra 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 (aiogram: bot.get_me()). La memoria es lo que ocupaban los procesos del bot 15 segundos después de que Telegram rechazara el token; el tiempo de arranque va desde lanzar Python hasta que la biblioteca informa de esa respuesta, así que incluye un viaje de ida y vuelta a Telegram. Ambos son la mediana de tres ejecuciones tras una ejecución de calentamiento.

Estas cifras son el mínimo de la biblioteca: sin chats, sin handlers trabajando, sin nada en caché. Tu propio código, los datos que guarda en memoria (por ejemplo los estados de conversación en el almacenamiento en memoria de aiogram) y el número de chats que atiende se suman a ellas, así que dimensiona el plan según lo que hace tu bot. Nuestra página anterior python-telegram-bot vs aiogram en PlayNHost midió una configuración distinta (Python 3.13, un bot ya construido y listo para arrancar), así que sus números no son comparables con estos.

Un bot mínimo de aiogram

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

aiogram>=3,<4

Y el código en bot.py:

import asyncio
import logging
import os
import sys

from aiogram import Bot, Dispatcher
from aiogram.filters import CommandStart
from aiogram.types import Message

dp = Dispatcher()


@dp.message(CommandStart())
async def start(message: Message) -> None:
    await message.answer("Hello! I am running on PlayNHost.")


async def main() -> None:
    bot = Bot(os.environ["BOT_TOKEN"])
    async with bot.context():
        await bot.delete_webhook()
        await dp.start_polling(bot)


if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO, stream=sys.stdout)
    asyncio.run(main())

Lee BOT_TOKEN, el nombre que usan los ejemplos del propio aiogram; el panel entrega el token a tu código con ese nombre y también como TELEGRAM_BOT_TOKEN, TOKEN y TELEGRAM_TOKEN. El registro a nivel INFO hace que aiogram imprima una línea que empieza por INFO:aiogram.dispatcher:Run polling for bot @your_bot cuando Telegram ha aceptado el token, y el panel lee esa línea para mostrar En línea en Telegram, así que no necesitas un print propio. delete_webhook() elimina un webhook que haya quedado de otro host antes de empezar el polling. async with bot.context() cierra la conexión del bot con Telegram cuando termina main(), también si termina con un error.

Si el token es incorrecto

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

TelegramUnauthorizedError: Telegram server says - Unauthorized

En un traceback completo, la clase aparece como aiogram.exceptions.TelegramUnauthorizedError. La primera llamada a Telegram falla (en el bot de arriba, delete_webhook(); sin ella, el getMe que hace start_polling), así que el bot se detiene enseguida 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 de nuevo el token: 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.

Otros dos casos se ven distintos. Un token con un espacio, o sin el número del bot y los dos puntos delante del secreto, falla antes de cualquier petición: Bot() comprueba el formato y lanza TokenValidationError con un mensaje que empieza por Token is invalid!. Un token revocado mientras el bot ya está haciendo polling no lo detiene: aiogram registra Failed to fetch updates - TelegramUnauthorizedError y lo intenta de nuevo cada pocos segundos, así que el proceso parece estar en marcha mientras nada responde. El aviso del panel es la forma de darte cuenta.

Lo que un host debe saber sobre aiogram

• Nombres del paquete y de la importación: ambos son aiogram. Instala con él aiohttp, pydantic, magic-filter, aiofiles y certifi.
• Versión de Python: aiogram 3.31 necesita Python 3.10 a 3.14. El Entorno de ejecución del panel Código ofrece exactamente 3.10 a 3.14, con 3.12 marcado como recomendado.
• El código de aiogram 2 no funciona en aiogram 3: se eliminó el Executor, así que executor.start_polling(dp) pasa a ser await dp.start_polling(bot). Un tutorial cuyo requirements.txt fija una versión 2.x, como aiogram==2.25.2, es código de la versión 2; consulta la pregunta más abajo.
• Un webhook que quedó de otro host: start_polling no lo elimina, y Telegram rechaza el polling mientras haya uno configurado, así que aiogram registra TelegramConflictError y lo reintenta. Mantén await bot.delete_webhook() como arriba, o haz clic en Quitar webhook en la página Bot, panel Telegram.
• Registro: sin logging.basicConfig, las líneas INFO de aiogram, incluida la de listo, no se muestran. En INFO también registra una línea por cada update (Update id=... is handled); en un bot con mucho tráfico añade logging.getLogger("aiogram.event").setLevel(logging.WARNING), que conserva la línea de listo.
• Qué updates llegan: si no pasas allowed_updates, start_polling pide a Telegram solo los tipos de update para los que tienes handlers.
• Una segunda copia: cuando otra copia hace polling con el mismo token, Telegram responde 409 Conflict y aiogram 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 aiogram en un entorno virtual. Comprueba que python3 --version dice 3.10 a 3.14.

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 ejecuta sudo chmod 600 /etc/tgbot.env:

BOT_TOKEN=123456789:your-token-from-botfather

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

[Unit]
Description=Telegram bot (aiogram)
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

Inícialo ahora y en cada arranque, y luego sigue su salida:

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

Las líneas de registro llegan al journal en el momento en que ocurren; PYTHONUNBUFFERED=1 hace lo mismo con cualquier print() que añadas, que Python de otro modo retiene en un búfer cuando no escribe en un terminal. systemctl stop tgbot envía SIGTERM, que start_polling gestiona deteniendo el polling y cerrando la sesión del bot. 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ú: actualizaciones del sistema, la versión de Python, el entorno virtual, reinstalar paquetes, el archivo de unidad, leer el journal y darte cuenta de cuándo el bot deja de responder. A cambio tienes root y puedes usar el modo webhook de aiogram si añades un dominio y HTTPS.
• En un plan de bots lo hace el panel: instala requirements.txt cuando cambia, vuelve a iniciar el bot tras un fallo, comprueba el token con Telegram antes de guardarlo, se lo entrega a tu código con cinco nombres, lee la consola y nombra 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 start_polling.

Consulta también Cómo usar una base de datos MySQL con un bot de aiogram (aiomysql).

Preguntas frecuentes

¿Puedo ejecutar un bot de aiogram 2?

Pásalo a aiogram 3 si puedes: la guía de migración de aiogram lista los cambios, empezando por el Executor eliminado. La última versión de aiogram 2, la 2.25.2, salió el 6 de octubre de 2023. Indica como compatibles Python 3.7 a 3.10 y necesita aiohttp anterior a 3.9, que PyPI ofrece como paquetes ya compilados solo hasta Python 3.11. Si necesitas que el código antiguo funcione antes de migrarlo, fija aiogram==2.25.2 en requirements.txt y pon el Entorno de ejecución en Python 3.10, la versión más reciente que indica.

¿Por qué mi bot de aiogram parece estar en marcha pero nunca responde?

aiogram sigue reintentando una vez iniciado el polling: con un token revocado en @BotFather, con otra copia que usa el mismo token y con un webhook que quedó en el bot. Lee las líneas que empiezan por Failed to fetch updates en la Console; el panel convierte cada uno de los tres casos en un aviso que nombra la causa, con un botón para el token y el webhook.

¿Dónde viven los estados FSM de aiogram?

Con el almacenamiento en memoria por defecto, en el proceso del bot: se pierden cuando el bot se reinicia, por ejemplo tras cambiar el código. Para conservarlos, usa un almacenamiento fuera del proceso, como el almacenamiento Redis de aiogram con un servidor Redis al que puedas acceder.

¿Necesito un webhook para mantener un bot de aiogram en línea?

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

aiogram funciona en todos los planes de bots de PlayNHost, desde STARTER (0,5 GB) en adelante. Compara los planes y haz clic en Crear servidor en alojamiento de bots de Telegram.