Telegram Ultimate Toolbox: Descargador Masivo, Clonador, Vigilante y Uploader con Docker

Tengo canales de Telegram donde comparten archivos importantes: documentos, vídeos, cursos, herramientas. Pero Telegram no tiene forma de descargar todo el contenido de un canal de golpe. Tienes que ir archivo por archivo, y si el canal tiene miles de mensajes, es una eternidad.

Mi motivación: Un día necesitaba respaldar un canal entero que estaba a punto de ser eliminado. Tenía cientos de archivos útiles y no quería perderlos. Empecé a descargar uno por uno y me di cuenta de que iba a tardar horas (o días). Además, algunos canales están en otros idiomas y necesitaba traducir los mensajes automáticamente.

También quería vigilar ciertos canales en tiempo real para recibir alertas cuando apareciera contenido relevante (ofertas de trabajo, descuentos, noticias). Y, con el tiempo, también quería subir vídeos a varios grupos de Telegram de forma automática cuando no estoy delante del ordenador. Pero Telegram no tiene esa función de alertas por palabras clave ni un uploader multi-grupo.

Así que hice Telegram Ultimate Toolbox: un script con cuatro módulos que resuelven todos estos problemas.

El problema

Telegram no ofrece una forma nativa de descargar grandes volúmenes de contenido, traducir automáticamente los mensajes, vigilar canales con alertas personalizadas ni subir vídeos a varios grupos de golpe. Las herramientas existentes suelen ser limitadas, poco seguras o no manejan bien las restricciones de canales protegidos.

La solución

Un script Python con TelegramClient (Telethon) que ofrece cuatro módulos principales: descarga masiva, clonación con traducción, vigilante de contenido y subidor automático a grupos. Las credenciales se almacenan cifradas con AES (Fernet) y el sistema de logs muestra el progreso con iconos coloreados por tipo de mensaje.

Arquitectura

Telegram Ultimate Toolbox
├── Telethon (TelegramClient)
│   ├── Descarga masiva (enlace/rango/ TXT)
│   ├── Clonación con traducción
│   ├── Vigilante en tiempo real
│   └── Uploader a grupos (subir_videos.py)
├── Bot API (python-telegram-bot)
│   ├── Comandos: /descarga, /tip, /concepto, /tool, /noticias
│   ├── Descarga de vídeos (yt-dlp + HLS fallback)
│   ├── Contenido IA (Gemini + Wikipedia)
│   └── Noticias scrapeadas (80+ fuentes)
├── Cifrado AES (Fernet)
│   ├── config.bin → API ID/Hash cifrados
│   └── secret.key → llave de cifrado
├── Filtro inteligente
│   ├── Lista negra de spam
│   └── Traducción automática (mtranslate)
└── Interfaz CLI
    ├── rich (paneles, logs con iconos)
    └── inquirerpy (menús interactivos)

Los 4 módulos

1. Descarga Masiva

Descarga contenido de canales de Telegram de tres formas:

El módulo maneja:

• Resolución de canales con caché (peer_cache)
• Descarga robusta con resume (archivos .part)
• Progreso en tiempo real por archivo
• Filtro de spam automático
• Traducción opcional de textos detectados

async def download_media_robust(client, message, folder):
    # Archivo temporal .part para resume
    temp_path = full_path + ".part"
    if os.path.exists(full_path):
        return True  # Ya existe, saltar
    
    with open(temp_path, 'wb') as f:
        await client.download_media(message, file=f, progress_callback=prog)
    os.rename(temp_path, full_path)

2. Clonación & Backup

Clona mensajes de un canal a otro con opciones avanzadas:

ID/Username del canal ORIGEN: @canal_origen
ID/Username del canal DESTINO: @canal_destino
¿Cuántos mensajes clonar?: 100
¿Descargar multimedia también? (s/n): s
¿Traducir contenido al clonar? (s/n): s

Características:

• Traducción automática: Traduce el contenido al clonar usando mtranslate
• Descarga de multimedia: Opción de descargar archivos adjuntos
• Filtro de spam: Salta mensajes que contengan palabras de la lista negra
• Límite configurable: Puedes clonar N mensajes específicos
• Velocidad controlada: Sleep de 0.8s entre mensajes para evitar rate limits

3. Modo Vigilante

Monitorea canales en tiempo real y envía alertas cuando detecta contenido relevante:

Palabras clave extra (separadas por coma): bitcoin, invertir, urgente

El vigilante:

• Escucha events.NewMessage en tiempo real
• Aplica el filtro de spam automático
• Compara con las palabras clave personalizadas
• Envía alertas a “me” (mensajes guardados) de Telegram
• Se detiene con Ctrl+C

@client.on(events.NewMessage)
async def handler(event):
    texto = event.message.message
    if procesar_texto_inteligente(texto) == "FILTERED_CONTENT" or \
       any(p in texto.lower() for p in palabras):
        await client.send_message('me', f"🔔 Alerta Vigilante:\n{texto}")

4. Modo Uploader (subir_videos.py)

Sube vídeos comprimidos a grupos de Telegram automáticamente. Es la última pieza del pipeline “Grabar → Comprimir → Subir a Telegram”: vigila una carpeta y por cada *_compressed.mp4 lo sube, con ruteo automático por keyword del directo.

# Setup de sesión (una vez, crea uploader.session)
docker compose run --rm uploader python /app/subir_videos.py --setup

# Descubrir tus chats/grupos (copia los IDs a grupos.json)
docker compose run --rm uploader python /app/subir_videos.py --list-chats

# Modo automático (bucle, sube cada intervalo)
docker compose up -d uploader

Características:

• Ruteo por keyword: el TwitchRecorder lee el título del directo y lo incrusta en el nombre (*_KW_<keyword>_compressed.mp4). El uploader sube el vídeo solo al grupo cuyo nombre coincida con la keyword; si no hay coincidencia, al default.
• Sesión propia: usa uploader.session, separada de la sesión del menú interactivo (ultimate_session). Así puedes correr el menú de descargas y el uploader a la vez sin conflictos.
• Límite de 2 GB: si un vídeo supera 2 GB, lo divide en partes con ffmpeg -c copy (sin recompresión) antes de subir.
• Registro de enviados (enviados.json): no reenvía lo ya subido y elimina el original al completar.
• Robusto: maneja credenciales corruptas, grupos.json mal formado, sesión vencida (sugiere --setup) y fallos por grupo sin marcar como enviado.
• Configurable por entorno (UPLOADER_API_ID, UPLOADER_INTERVALO, UPLOADER_CARPETAS, UPLOADER_SESION, UPLOADER_GRUPOS, UPLOADER_ENVIADOS, UPLOADER_PARTES…).

// grupos.json — ruteo por keyword
{
    "default": -100999888777,
    "grupos": [
        { "nombre": "prueba", "id": -100111222333 },
        { "nombre": "sendo", "id": -100444555666 }
    ]
}

Seguridad: cifrado AES

Las credenciales de la API de Telegram se almacenan cifradas con Fernet (AES-CBC):

Flujo de cifrado

1. Usuario introduce API ID y API HASH
2. Se genera una llave Fernet (si no existe secret.key)
3. Los datos se cifran con Fernet.encrypt()
4. Se guardan en config.bin (binario)
5. La llave se guarda en secret.key (NUNCA commitear)

Flujo de descifrado

key = open("secret.key", "rb").read()
cipher = Fernet(key)
with open("config.bin", "rb") as f:
    datos_cifrados = f.read()
    datos_planos = cipher.decrypt(datos_cifrados).decode('utf-8')
    config = json.loads(datos_planos)

Archivos importantes

Filtro de spam

Lista negra predefinida que se aplica automáticamente:

SPAM_LIST = [
    "crypto", "ganar dinero", "casino", "poker", 
    "estafa", "bet", "sex", "porn", "gore", "nude"
]

El filtro se aplica en:

• Descarga masiva: salta mensajes que contengan estas palabras
• Clonación: no clona contenido filtrado
• Vigilante: marca como alerta si detecta contenido filtrado

Sistema de logs

Cada mensaje de log tiene un icono y color según su tipo:

Ejemplo de salida:

  14:32:15 ℹ Módulo de Descarga Masiva
  14:32:18 ℹ Cargados 45 enlaces desde enlaces.txt
  14:32:19 ↓ Bajando: video_2026.mp4
    -> video_2026.mp4: 67.3%
  14:32:25 ✓ Completado: video_2026.mp4
  14:32:26 🚫 Mensaje 12345 bloqueado por filtro.
  14:32:27 📝 ID 12346: Este es un mensaje traducido al español...

Generador de sesiones portátiles

Para generar un token de sesión que se pueda usar en otros dispositivos:

# Con Docker
docker compose run --rm telegram python test_string.py

# Sin Docker
python test_string.py

El token generado (ultimate_session.session) contiene las credenciales de autenticación. Cópialo a tu otro dispositivo y úsalo como archivo de sesión.

Uso con Docker

cd downloader_telegram
docker compose build
docker compose up                # menú interactivo (descarga/clonado/vigilante)

# Uploader (pipeline "Grabar → Comprimir → Subir"):
docker compose up -d uploader    # vigila /comprimidos y sube a los grupos
docker compose logs -f uploader  # logs del uploader

# Bot de Telegram (@jorbencas_bot):
docker compose up -d telegram_bot    # arranca el bot API
docker compose logs -f telegram_bot  # logs del bot

Contenedores

Variables de entorno del uploader

Instalación

¿Cómo instalar el bot, el uploader y el CLI interactivo? Consulta la guía de instalación completa — con Docker, sesiones, grupos, credenciales y cifrado AES.

Menú principal

╔═══════════════════════════════════════════════════════════╗
║  📦 TELEGRAM TOOLBOX                                      ║
║  Descargador · Clonador · Vigilante · Uploader             ║
╚═══════════════════════════════════════════════════════════╝

▸ Selecciona módulo:
  📥  Descargas Masivas (Enlace/Rango/TXT)
  🔄  Clonación & Backup (Filtro + Traducción)
  👁️   Modo Vigilante (Alertas por palabras)
  ─────────────────
  🚪  Re-configurar / Salir

Tecnologías

Requisitos

• Python 3.8+
• Cuenta de Telegram con API ID y API Hash (de my.telegram.org)
• (Opcional) Docker

Peculiaridades

• Auto-setup: Instala dependencias automáticamente si faltan
• Resume de descargas: Si se interrumpe, continúa desde donde quedó (archivos .part)
• Caché de canales: Resuelve entidades de canales una sola vez y las reutiliza
• Rate limit controlado: Sleep de 0.8s entre mensajes para no ser bloqueado
• 2FA soportado: Maneja automáticamente la verificación en dos pasos
• Sesión persistente: No necesita re-login entre ejecuciones
• Uploader multi-grupo: Sesión propia (uploader.session), sin conflictos con el menú interactivo
• División >2 GB: Corta vídeos grandes en partes con ffmpeg -c copy antes de subir