El choque

Hoy intentaba pasar un audio de un canal de Telegram al pipeline de transcripcion local (Whisper en la RTX 2060). Tengo un bot personal, ambrosio-pass-bot, con su token y su chat ID guardados en pass. Lo uso a diario para mandarme notas de voz, alertas y reportes desde scripts.

Pedi el archivo via API:

curl -sf "https://api.telegram.org/bot${BOT}/getFile?file_id=${FID}"

Respuesta:

{
  "ok": false,
  "error_code": 400,
  "description": "Bad Request: file is too big"
}

23 MB. Ni grande ni nada raro: un m4a de veinticuatro minutos. Pero el Bot API tiene un muro hormigonado en 20 MB para descargas. Subir va hasta 50 MB, bajar 20 MB y punto. Llevo meses usando bots y nunca habia tropezado con esto porque siempre eran notas de voz cortas o textos.

Lo googleo. Y descubro tdl. Un proyecto de 2021, 9k estrellas en GitHub, y yo sin enterarme.

Bot API contra MTProto, en una tabla

Telegram tiene dos APIs publicas, no una:

El Bot API es un envoltorio HTTP que el equipo de Telegram pone delante del MTProto real. Comodo, pero capado. MTProto es lo que usa la app oficial: rapido, multi-conexion, sin esos limites.

La pieza que me faltaba: MTProto tambien lo puede usar un script tuyo, no es exclusivo de la app oficial.

Que es tdl

tdl (Telegram Downloader) es un CLI escrito en Go que habla MTProto con tu cuenta personal. Una vez logueado, hace lo que el cliente oficial hace pero por linea de comandos:

• Listar chats, canales y grupos.
• Bajar archivos individuales por URL (t.me/c/... o t.me/canal/123).
• Bajar mensajes en bloque de un chat entero.
• Subir archivos a un chat.
• Reenviar mensajes entre chats.
• Exportar historial.

Soporta multi-conexion (paraleliza el download en varios threads), reanuda si se corta y tiene un sistema de extensiones. En la practica, una descarga que el cliente oficial te hace en treinta segundos, tdl la hace en quince.

Como se monta

Necesitas dos cosas:

1. API_ID y API_HASH

No los proporciona BotFather. Estan en https://my.telegram.org -> "API development tools". Login con tu numero de Telegram (te llega el codigo a la propia app). Te da un par api_id (numerico) + api_hash (string).

Estos son tuyos para siempre. Se guardan una vez y a otra cosa:

pass insert telegram/api-id
pass insert telegram/api-hash

2. Login con tu cuenta

El primer arranque pide telefono y codigo (te llega como mensaje de Telegram, no SMS). Crea una sesion en ~/.config/tdl/ que se reutiliza:

tdl login -T desktop  # te pide telefono + codigo

Despues de eso, el comando ya tira solo.

Comandos que de verdad uso

Listar mis chats

tdl chat ls

Saca un JSON con id, tipo y titulo de cada chat. Util para sacar el chat-id de un grupo o canal.

Bajar un mensaje concreto

tdl dl -u "https://t.me/c/1234567890/42" -d ~/audios

La URL la sacas con click derecho sobre el mensaje en Telegram Desktop -> "Copy message link".

Bajar todos los archivos de un chat

tdl chat export -c <chat-id> -o messages.json
tdl dl -f messages.json -d ~/dump

Se exporta el historial a JSON, tdl reconoce los media y los baja todos.

Subir un archivo grande

tdl up -p video.mkv -c <chat-id>

Sin el limite de 50 MB del Bot API. Hasta 2 GB por archivo.

La parte que me toca: integrarlo en mi pipeline

El plan es trivial:

1. tdl en el systemPackages del flake.nix.
2. API_ID=/=API_HASH en pass (telegram/api-id, telegram/api-hash).
3. Sesion tdl en ~/.config/tdl/ (replicada por Syncthing entre las cinco maquinas, igual que la sesion de Claude Code).
4. Una funcion en el helper telegram-notify que detecte ficheros >19 MB y haga fallback automatico a tdl up en vez de sendDocument.
5. Para descarga, un wrapper telegram-fetch <message-url> que tire de tdl dl y devuelva la ruta local.

Con eso, mi pipeline de voz pasa de "todo bajo 20 MB" a "manda lo que sea", sin tocar el resto del codigo.

Por que no lo conocia

Llevo dos anos con bots de Telegram y nunca me paso. La razon es boba: los bots que escribia mandaban mensajes y notas de voz cortas, nunca recibian audios de 24 minutos. El muro estaba ahi todo el rato, simplemente nunca lo toque.

Es una leccion barata: las APIs comodas (un token, HTTP, JSON) tienen letra pequena. La API "incomoda" (login con tu cuenta, protocolo binario, MTProto) la hicieron asi porque la otra es un subset suyo. Cuando el subset no llega, hay que bajar al nivel siguiente.

Avisos

• Si Telegram detecta que estas usando tdl con un patron raro (descargas masivas, scraping de canales gigantes), pueden tumbarte la sesion. Para uso personal -mis chats, mis archivos- ni se entera.
• La sesion de tdl es credencial sensible. Quien la robe se loguea como tu en Telegram. Tratala como una clave SSH: permisos 600, no la subas a git, gpg-agent si quieres mas paranoia.
• API_ID=/=API_HASH no son tan criticos como la sesion (no permiten loguearse solos), pero tampoco van en publico.

Cierre

Hoy aprendi que llevaba anos usando Telegram con la mitad de la API. Bot API para lo facil, tdl para cuando el archivo pesa de verdad. Las dos coexisten en la misma cuenta sin pisarse: el bot sigue funcionando con su token, mi cuenta personal con tdl aparte.

Repo: https://github.com/iyear/tdl