Telegram è pieno di canali utili, corsi, archivi, documentazione, contenuti che vuoi tenere. Il problema è che non esiste un modo nativo per scaricare i media in blocco, selezionare intervalli di messaggi o gestire canali privati con inviti. Puoi farlo manuale, uno alla volta. Oppure automatizzarlo.

Da lì è nato Telegram Media Downloader: uno script Python che si connette all’API di Telegram, recupera i messaggi di un canale o gruppo, ti mostra cosa c’è e ti lascia scegliere cosa scaricare. Niente UI, niente servizi terzi, niente abbonamenti. Lo avvii dal terminale e fa esattamente quello che gli dici.

  • Telethon per parlare con le API di Telegram: client asincrono, completo e affidabile
  • tqdm per la barra di progresso durante il download: perché sapere quanto manca conta
  • config.json per tenere le credenziali fuori dal codice, senza complicazioni

Come funziona

Il flusso è lineare: fornisci il link o l’identificativo del canale, lo script recupera la lista dei messaggi con i media allegati, tu scegli cosa scaricare, un singolo messaggio, un intervallo, o tutto. Il download parte con progresso in tempo reale.

Alla fine, i file atterrano nella cartella che hai configurato, con i nomi originali preservati. E se qualcosa va storto, c’è un log.txt che tiene traccia degli errori senza interrompere tutto.

La validazione dell’input

Il primo problema da risolvere era accettare link in formati diversi senza rompere le API call. Telegram ha almeno sei modi per identificare un canale:

patterns = [
    r'^https:\/\/t\.me\/\+\w+$',          # Link diretto con "+"
    r'^https:\/\/t\.me\/joinchat\/\w+$',  # Link di invito con "joinchat"
    r'^https:\/\/t\.me\/\w+$',            # Link generico per canali
    r'^https:\/\/web\.telegram\.org\/k\/#-?\d+$',  # Web Telegram con ID numerico
    r'^@\w+$',                             # Username del canale o gruppo
    r'^-?\d+$'                             # ID numerico
]

Ogni pattern gestisce un caso reale. Se l’input non matcha nessuno, lo script si ferma subito. Meglio un errore chiaro che una chiamata API destinata a fallire.

Validare non basta: l’API di Telegram vuole solo la parte essenziale del link, non l’URL completo. La funzione clean_link si occupa di questo:

def clean_link(link):
    if link.startswith("https://web.telegram.org/k/#"):
        return link.split("#")[-1]
    if "joinchat" in link:
        return link.split("/")[-1]
    return link

Semplice, diretto. Entra un URL, esce l’identificativo pulito che Telethon sa usare.

Gestione del Flood Wait

Telegram impone limiti sulle richieste API. Se li superi, ti blocca per un po’. Lo script lo gestisce in modo trasparente:

except errors.FloodWaitError as e:
    print(f"Flood control attivo, riprovo tra {e.seconds} secondi...")
    await asyncio.sleep(e.seconds)

Invece di crashare o spammare richieste, aspetta esattamente il tempo che Telegram indica e poi riprende. Non c’è niente da fare funziona da solo.

La selezione dei messaggi

Questa è la parte che mi stava più a cuore. Non volevo un “scarica tutto o niente”: volevo la granularità. Puoi inserire:

  • 5 → solo il messaggio 5
  • 10,15,18 → messaggi specifici
  • 18-30 → un intervallo
  • 10,15,18-30 → combinazione di entrambi
  • T → tutto
ranges = selection.split(',')
selected_indices = []
for r in ranges:
    if '-' in r:
        start, end = map(int, r.split('-'))
        selected_indices.extend(range(start, end + 1))
    else:
        selected_indices.append(int(r))

Il risultato è una lista di ID che viene passata al download. Niente magie, logica pulita.

Il download con progresso

Telethon gestisce il download asincrono, tqdm mostra quanto hai scaricato in tempo reale:

with tqdm(total=file_size, unit='B', unit_scale=True, unit_divisor=1024, desc=file_name) as pbar:
    def progress_callback(current, total):
        pbar.update(current - pbar.n)

    await message.download_media(file=file_path, progress_callback=progress_callback)

Il file viene salvato con il nome originale. Se non c’è un nome (capita con alcuni tipi di documento), genera un fallback con l’ID del documento.

Configurazione

Tutto quello che cambia tra un utilizzo e l’altro sta in config.json:

{
    "API_ID": "xxxxxxx",
    "API_HASH": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "SESSION_NAME": "app_session",
    "PATH_DOWNLOAD": "/path/here"
}

API_ID e API_HASH li ottieni da my.telegram.org bastano pochi minuti. PATH_DOWNLOAD è la cartella dove vuoi i file. La prima volta che avvii lo script, Telethon crea un file di sessione con il nome che hai scelto in SESSION_NAME: da lì in poi non chiede più le credenziali.

Installazione e avvio

pip install -r requirements.txt
python app.py

Dipendenze minimali: Telethon per le API, tqdm per la progressbar, più le librerie crittografiche che Telethon porta dietro (pyaes, rsa, pyasn1).

E poi?

  • Filtrare per tipo di media (solo video, solo foto, solo documenti)
  • Modalità di aggiornamento incrementale — scarica solo i nuovi
  • Export della lista messaggi in CSV o JSON
  • Interfaccia TUI con Textual per chi vuole qualcosa di visuale

Conclusione

Telegram Media Downloader nasce da un’esigenza concreta: scaricare contenuti in modo preciso, senza affidarsi a bot, servizi web o strumenti che fanno troppo. Lo script fa una cosa sola recuperare e scaricare media da Telegram e la fa bene.

Il codice è su GitHub, licenza GPL, fork e pull request sono benvenuti. Se hai un canale pieno di file che aspettano solo di essere scaricati, sai cosa fare.