Instalación de Telegram Toolbox: Bot, Uploader y Descargador Masivo

Telegram Ultimate Toolbox tiene 4 módulos: descarga masiva, clonación con traducción, vigilante de contenido y uploader automático. Pero para que funcione, necesitas configurar varias cosas: credenciales de Telegram, sesiones de autenticación, grupos destino, y el token del bot. Cada pieza tiene su porqué.

1. Por qué Telegram Toolbox (y no otro bot)

¿Por qué dos sistemas (Telethon + Bot API)? Porque son cosas diferentes:

• Telethon = se autentica como usuario real. Puede acceder a canales protegidos, descargar archivos grandes, leer mensajes privados.
• Bot API = se autentica como bot. Puede recibir comandos (/help, /tip) y enviar mensajes, pero no puede acceder a canales protegidos.

El uploader usa Telethon (usuario real) para subir vídeos a canales donde un bot no tendría acceso.

2. Requisitos previos

3. Obtener el API ID y Hash de Telegram

Este es el paso más confuso. Telegram exige registrar una “aplicación” para usar su API.

Qué son: Son credenciales que identifican tu aplicación ante Telegram. No son el token de un bot.

Cómo obtenerlos:

1. Ve a my.telegram.org/apps
2. Inicia sesión con tu número de teléfono de Telegram. Formato: +34 612 345 678 (España) o +52 55 1234 5678 (México). Incluye el prefijo internacional sin espacios ni guiones.
3. Telegram te enviará un código de verificación por el propio Telegram (no por SMS). Es un código de 5 dígitos. Ábrelo en la app de Telegram, en el chat con “Telegram” (el servicio oficial).
4. Haz clic en “Create new application”
5. Rellena el formulario:
   • App title: da igual, puedes poner “devjobs”
   • Short name: también da igual, “devjobs”
   • Platform: selecciona “Desktop” (da igual cuál elijas)
6. Copia el api_id (numérico, como 39937314) y el api_hash (hexadecimal, como be1b57db99dfe149a2a06db3b47d68c3)

¿Por qué no usar un bot? Porque el uploader necesita acceder a canales protegidos. Un bot no puede leer canales donde no es administrador. Un usuario real sí puede.

Guarda estos valores: Los necesitarás en el paso 5.

4. Obtener el token del bot (opcional)

Si quieres usar el bot interactivo (@jorbencas_bot), necesitas un token.

Cómo obtenerlo:

1. Abre Telegram (en el móvil o en el escritorio) y busca @BotFather. Es el bot oficial de Telegram para crear bots.
2. Envía /newbot (escribe /newbot y dale a enviar)
3. BotFather te preguntará: “¿Cómo se llamará tu bot?” — Escribe un nombre descriptivo, ej: “Mi Bot”
4. BotFather te preguntará: “¿Cuál será el username?” — Debe terminar en bot. Ejemplo: mibot_bot. Si no te deja, prueba con otro nombre.
5. BotFather te dará un token como 8580222159:AAE4e21gzeq6q.... Copia y guarda ese token inmediatamente — solo se muestra una vez.
6. Si pierdes el token, puedes pedirlo de nuevo con /mybots → selecciona tu bot → “API Token”

¿Por qué es opcional? Porque el uploader y el CLI interactivo no necesitan el bot. Solo lo necesitas si quieres comandos como /tip, /descarga, /noticias.

5. Configurar el archivo .env

El archivo .env es donde le dices al sistema quién eres. Sin él, nada funciona.

5.1. Crear el archivo

Crea downloader_telegram/.env:

# API de Telegram (obligatorio para uploader y CLI)
API_ID=39937314
API_HASH=be1b57db99dfe149a2a06db3b47d68c3

# Bot de Telegram (obligatorio para el bot interactivo)
BOT_TOKEN=8580222159:AAE4e21gzeq6q...

# Gemini API (opcional, para tips y herramientas IA)
GEMINI_API_KEY=tu_api_key

5.2. Por qué cada variable

5.3. Dónde va el archivo

En la raíz de downloader_telegram/:

devjobs/
└── downloader_telegram/
    ├── .env                    ← AQUÍ
    ├── docker-compose.yml
    └── ...

6. Crear sesión de Telegram

La sesión es un archivo que guarda tus credenciales de autenticación. Es como una cookie persistente: la creas una vez y se reutiliza.

6.1. Crear sesión del CLI interactivo

cd downloader_telegram

# Construir la imagen Docker
docker compose build

# Ejecutar el generador de sesión
docker compose run --rm telegram python test_string.py

Qué pasará:

1. El script te pedirá tu número de teléfono. Formato: +34612345678 (sin espacios, sin guiones, con el prefijo internacional).
2. Telegram te enviará un código de verificación por el propio Telegram (no por SMS). Ábrelo en la app de Telegram, en el chat con “Telegram”. Es un código de 5 dígitos.
3. Si tienes 2FA (verificación en dos pasos) configurada, también te pedirá tu contraseña. Es la contraseña que configuraste cuando activaste la verificación en dos pasos en Telegram (Ajustes → Privacidad → Verificación en dos pasos).
4. Al finalizar, se crea sessions/tg_menu.session.

¿Por qué en Docker? Para no instalar telethon, cryptography ni otras dependencias en tu sistema. Docker trae todo.

6.2. Crear sesión del uploader

El uploader usa una sesión diferente a la del CLI. Esto es intencional: puedes correr el menú de descargas y el uploader a la vez sin conflictos.

# Crear sesión del uploader (una vez)
docker compose run --rm uploader python /app/subir_videos.py --setup

¿Qué se genera? Un archivo sessions/uploader.session.

¿Por qué dos sesiones? Porque si ambas usaran la misma sesión, Telegram las desconectaría mutuamente (solo permite una conexión por sesión).

7. Configurar grupos de Telegram

Necesitas decirle al sistema a qué grupo subir los vídeos.

7.1. Descubrir tus grupos

# Listar todos tus chats y grupos
docker compose run --rm uploader python /app/subir_videos.py --list-chats

Esto te mostrará algo como:

Chat: Stream Tecnologia
  ID: -1004332325883
  Tipo: group
  Tiene topics: sí

Chat: Mi grupo de prueba
  ID: -100111222333
  Tipo: group
  Tiene topics: no

¿Cómo interpretar esto? El ID es el número que necesitas copiar. Los IDs de grupos son negativos y empiezan por -100. Si “Tiene topics: sí”, el grupo tiene el sistema de foros activado (cada tema es un hilo independiente).

7.2. Crear config/grupos.json

Copia los IDs a downloader_telegram/config/grupos.json:

{
    "default": -100999888777,
    "grupos": [
        { "nombre": "mi_grupo", "id": -100111222333 },
        { "nombre": "sendo", "id": -100444555666 }
    ]
}

• default: Grupo por defecto si no hay coincidencia de keyword
• grupos: Lista de grupos con nombre (para ruteo por keyword) e ID

¿Qué es nombre? El nombre que se usa para ruteo por keyword. Si un vídeo se llama OnePiece_KW_sendo_compressed.mp4, se sube al grupo cuyo nombre es “sendo”.

7.3. Verificar que el bot es administrador

Si usas el uploader, el bot (o tu usuario) debe ser administrador del grupo. Sin permisos de administración, no puede enviar mensajes ni crear temas.

Cómo añadir el bot como administrador:

1. Abre el grupo en Telegram
2. Toca el nombre del grupo → “Administradores”
3. “Añadir administrador”
4. Busca tu bot por username
5. Dale permisos de “Enviar mensajes” y “Añadir temas”

8. Variables de entorno del uploader

El uploader tiene variables adicionales que puedes configurar:

9. Arrancar los servicios

9.1. CLI interactivo (descarga/clonado/vigilante)

docker compose up

# Seleccionar: Descargas Masivas, Clonación o Vigilante

9.2. Uploader automático (pipeline)

# El uploader vigila comprimidos/ y sube a Telegram
docker compose up -d uploader

# Ver logs
docker compose logs -f uploader

9.3. Bot de Telegram

# Configurar variables en .env (si no lo has hecho)
echo "BOT_TOKEN=tu_token" >> .env
echo "BOT_ADMINS=tu_user_id" >> .env

# Arrancar el bot
docker compose up -d telegram_bot

# Ver logs
docker compose logs -f telegram_bot

¿Cómo obtengo mi user ID? Envía un mensaje a tu bot y luego abre https://api.telegram.org/botTU_TOKEN/getUpdates. Busca "from":{"id":12345678} — ese número es tu user ID.

10. Cómo funciona el uploader por dentro

El uploader (subir_videos.py) es el consumidor final del pipeline de compresión. No es un bot que espera comandos: es un daemon que vigila una carpeta y, cada UPLOADER_INTERVALO (60s), hace lo siguiente con cada *_compressed.mp4 que encuentra en /comprimidos:

10.1. El ciclo completo de subida

1. LEER archivo en /comprimidos/<nombre>_compressed.mp4
        │
        ▼
2. Extraer canal y keyword del NOMBRE del archivo
   "sendo_2026-08-13_20-15-00_KW_diario_compressed.mp4"
        │  canal = primer token ("sendo")
        │  keyword = lo que sigue a "_KW_" ("diario")
        ▼
3. RUTEO: ¿a qué grupo/tema va?
        ├─ grupos.json → grupos cuyo nombre coincide con la keyword
        ├─ ¿el grupo tiene foros? → busca tema por canal, por keyword, o el general
        └─ sin coincidencia → grupo "default"
        ▼
4. ¿Tamaño > 2GB? (límite de Bot API / subida estable)
        ├─ NO → envía el archivo entero
        └─ SÍ → DIVIDIR: ffmpeg -ss ... -t 5400 → partes de 90 min
                en /app/partes/<base>_part01.mp4, _part02.mp4, ...
                (cada parte se envía con sufijo "(n/total)" en el caption)
        ▼
5. ENVIAR con send_file (Telethon), thumb generada en el segundo 2,
   attributes=atributos_video → supports_streaming=true (reproducción en línea)
        ▼
6. marcar_enviado(): guarda la ruta absoluta en enviados.json  (dedup)
7. LIMPIAR: borra el mp4, el *_episodios.json, el original en .processed/
   y las partes de /app/partes

🔗 Este ciclo es el consumidor final del pipeline del Ecosistema Devjobs: los *_compressed.mp4 los produce el monitor de FFmpeg (ciclo de compresión).

10.2. Qué es la carpeta partes/

Montada como data/pipeline/partes → /app/partes (y como ../data/pipeline/partes en el docker-compose.yml), es un área de trabajo temporal:

• Se usa ÚNICAMENTE cuando un vídeo supera los 2 GB.
• dividir_video() (subir_videos.py) corta el vídeo en trozos de 90 minutos (_part01.mp4, _part02.mp4…) sin re-comprimir (-c copy), para que sea rápido y no pierda calidad.
• Se descartan partes de menos de 1 MB.
• Tras subir todas las partes, el uploader borra la carpeta (PARTES_DIR).

No tienes que crearla manualmente: el componente mkdir la crea solo, y el bootstrap_instalar.sh también la crea junto a las demás carpetas de data/.

Ojo, no confundir con las partes del TwitchRecorder (las __parte2.mp4 que se generan cuando un directo cambia de plataforma a mitad de emisión). Esas las concatena el propio recorder al terminar. La carpeta partes/ es solo el troceado para Telegram.

10.3. El ruteo por keyword (grupos.json)

El uploader no “sabe” de contenidos: decide el destino mirando el nombre del archivo.

Cada vídeo que se sube queda registrado en enviados.json para no enviarlo dos veces aunque el archivo aparezca de nuevo en la carpeta.

10.4. Las 3 sesiones (y por qué NO chocan)

El projeto usa sesiones separadas para cada rol, porque Telegram solo permite una conexión activa por sesión:

Como cada daemon monta su propia sesión (docker-compose.yml), puedes descargar y subir a la vez sin que Telegram te desconecte.

11. Seguridad: cifrado AES

Las credenciales se almacenan cifradas con Fernet (AES-CBC):

¿Por qué cifrar? Porque el API ID y Hash dan acceso a tus canales de Telegram. Si alguien los obtiene, puede leer tus mensajes.

¿Qué pasa si borro secret.key? Pierdes acceso a config.bin. Tendrías que volver a ejecutar --setup para generar nuevas credenciales.

12. Verificación

# Comprobar que todo está corriendo
docker compose ps

# Probar el bot en Telegram
# Enviar /ping a @jorbencas_bot

# Probar una descarga
docker compose run --rm uploader python /app/subir_videos.py --help

13. Sin Docker

Si prefieres instalar directamente:

cd downloader_telegram
python3 -m venv .venv
source .venv/bin/activate
pip install telethon mtranslate cryptography cryptg rich inquirerpy yt-dlp
python test_download_protected_content_telegram.py

¿Por qué no se recomienda? Porque telethon, cryptography y otras dependencias tienen versiones específicas. Docker te da una versión fija y reproducible.

Troubleshooting

¿Quieres ver cómo funciona el pipeline completo? Consulta:

• Instalación del Ecosistema Devjobs: Pipeline Completo desde Cero
• Instalación de FFmpeg + yt-dlp: Conversor de Vídeo
• Telegram Ultimate Toolbox: Descargador y Uploader con Docker

🪜 Siguiente nivel

Con el toolbox funcionando, sigue escalando el ecosistema:

1. Python de 0 a 100 — el lenguaje que mueve Telethon y todos tus scripts: Guía de Python: De 0 a 100.
2. El pipeline completo — grabar, comprimir y subir en una sola cadena: Instalación del Ecosistema Devjobs.
3. Conversor de vídeo con Docker — el eslabón que comprime antes de subir: Instalación de FFmpeg + yt-dlp.
4. Docker de 0 a 100 — domina los contenedores que arrancas aquí: Guía de Docker: De 0 a 100.

🔗 Enlaces y recursos

• Telegram — My.apps (API ID y Hash)
• BotFather — crear y gestionar bots
• Documentación de Telethon
• Telegram Bot API — documentación
• Google AI Studio — API Key de Gemini