Skip to main content

Downloading files

The downloader package fetches files by their tg.InputFileLocationClass, transparently following CDN redirects and downloading in parallel chunks.

import "github.com/gotd/td/telegram/downloader"

d := downloader.NewDownloader()

The telegram.Client also exposes a ready-made one as client.Downloader().

Downloading to a destination​

Download returns a builder with terminal methods:

// To a file on disk.
_, err := d.Download(client.API(), location).ToPath(ctx, "out.jpg")

// To any io.Writer (a buffer, an HTTP response, …).
_, err = d.Download(client.API(), location).Stream(ctx, w)

Both return the tg.StorageFileTypeClass describing the downloaded content.

Getting a location​

You rarely build an InputFileLocation by hand. Most media you encounter — in a message, a participant's photo, a document — exposes one. The query helpers make this easy: an Elem.File() from the messages iterator gives you both a name and a location, as in the save-media example:

import "github.com/gotd/td/telegram/query/messages"

file, ok := messages.Elem{Msg: msg}.File()
if !ok {
	return nil // message has no downloadable media
}

if _, err := d.Download(client.API(), file.Location).ToPath(ctx, file.Name); err != nil {
	return err
}

Tuning​

d := downloader.NewDownloader().
	WithPartSize(512 * 1024). // chunk size (must divide 1 MB / be a multiple of 4 KB)
	WithAllowCDN(true)         // allow CDN redirects

CDN downloads must also be permitted on the client via Options.AllowCDN.

Bulk downloads​

To back up many files, combine the downloader with a pagination iterator and a concurrency limiter such as golang.org/x/sync/errgroup, optionally throttled by the ratelimit middleware. The gif-download example downloads every saved GIF this way.