download

Download and decrypt media from a message.

Only use download when you need the plaintext bytes (processing, transcoding, re-upload). To forward existing media unchanged, reuse the original message’s CDN fields directly — no download required. See media forwarding via CDN reuse.

download and its siblings need a connected Client for most media — they ask the server for CDN hosts and an auth token (cached and refreshed automatically, not fetched on every call). The exception is static_url media (newsletter/channel content), which skips that round trip entirely — see the note below. If you’ve persisted a message’s CDN fields and want to download after the session has disconnected, use MediaDownloader instead — it needs no Client at all.

pub async fn download(
    &self,
    downloadable: &dyn Downloadable
) -> Result<Vec<u8>, anyhow::Error>

&dyn Downloadable

required

Any message type that implements the Downloadable trait. Includes:

ImageMessage
VideoMessage
AudioMessage
DocumentMessage
StickerMessage
ExternalBlobReference (app state)
HistorySyncNotification

Vec<u8>

Decrypted media bytes. For encrypted media (E2EE), automatically decrypts using AES-256-CBC and verifies HMAC-SHA256. For plaintext media (newsletters/channels), validates SHA-256 hash.

Example: download image

use waproto::whatsapp as wa;

// From a received message
if let Some(image_msg) = message.image_message {
    let image_bytes = client.download(image_msg.as_ref()).await?;
    std::fs::write("downloaded_image.jpg", image_bytes)?;
}

Example: download with error handling

match client.download(downloadable).await {
    Ok(data) => {
        println!("Downloaded {} bytes", data.len());
        // Process data...
    }
    Err(e) => {
        eprintln!("Download failed: {}", e);
        // Fallback logic...
    }
}

Recovering the CDN status by type

download still returns bare anyhow::Error, but as of PR #1195 the status the CDN refused is recoverable by type via ErrorChainExt::http_status() instead of only by parsing the message:

use whatsapp_rust::ErrorChainExt;

match client.download(downloadable).await {
    Ok(data) => { /* ... */ }
    Err(e) => {
        let cause: &(dyn std::error::Error + 'static) = e.as_ref();
        match cause.http_status() {
            // 500/502/503/504 are the CDN statuses normally worth a retry;
            // 501/505 mean the request itself is unsupported and won't
            // succeed on a resend. Apply your own policy per status.
            Some(429) | Some(500) | Some(502) | Some(503) | Some(504) => {
                /* worth backing off and retrying later */
            }
            Some(status) => eprintln!("CDN refused with {status}: {e}"),
            None => eprintln!("no HTTP refusal status recoverable, inspect the cause: {e}"),
        }
    }
}

None doesn’t mean no HTTP exchange took place — it means no refused status was attached. A socket that never connected reports None, but so does a body that downloaded successfully and then failed decryption or hash validation: neither case has a CDN status to recover, so there’s nothing to forward upstream. Inspect the underlying cause (cause.source() or the message) rather than assuming either case is always yours to fix.

Automatic retry and URL re-derivation

All download methods handle three categories of CDN errors automatically:

Auth errors (401/403): The client invalidates the cached media connection, fetches fresh credentials, and retries the download once.
Media not found (404/410): When a media URL has expired or the file has been relocated, the CDN returns 404 or 410. The client treats this the same as an auth error — it invalidates the cached connection, re-derives download URLs with fresh credentials and hosts, and retries once. This matches WhatsApp Web’s MediaNotFoundError handling.
Other errors (e.g., 500): The client tries the next available CDN host without refreshing credentials. Hosts are tried in priority order (primary first, then fallback).

For streaming downloads (download_to_writer), every attempt — including the first — starts by truncating the writer to empty via DownloadWriter::truncate and rewinding it, so a host that streamed out plaintext before failing its MAC can’t leave a tail behind a shorter successful retry. If every host fails, the writer is truncated to empty one final time on a best-effort basis rather than left holding unverified bytes. For in-memory downloads (download()), each retry gets a fresh buffer rather than reusing the previous one, for the same reason. If every retry is exhausted, the status of the final refusal survives into the error download/download_to_writer return — recover it with ErrorChainExt::http_status() as shown above rather than parsing the message.

This classification reads status_code off a successfully completed HTTP exchange — it never sees a status that a custom HttpClient implementation turned into an Err. If you provide your own HttpClient, see the non-2xx-as-Ok contract it must follow for this retry logic to work at all.

static_url media (newsletter/channel content fetched from a fixed CDN URL) skips the media-conn round trip entirely: download and its siblings only ask the server for hosts when the downloadable has no static_url.

download_to_writer

Download media to a writer using streaming when available, with automatic buffered fallback. This is the method to use for downloading straight to a file — pass a File or BufWriter<File>. When the HTTP client supports streaming (supports_streaming() returns true), the entire HTTP download, decryption, and file write happen in a single blocking thread with ~40KB memory usage regardless of file size. When streaming is not available, the method automatically falls back to a buffered download — fetching the full response into memory, then decrypting and writing to the writer. This ensures download_to_writer works with any HttpClient implementation. The writer must implement DownloadWriter rather than plain Write + Seek — see that section for why, and for what a custom writer needs to add.

pub async fn download_to_writer<W: DownloadWriter + Send + 'static>(
    &self,
    downloadable: &dyn Downloadable,
    writer: W,
) -> Result<W, anyhow::Error>

&dyn Downloadable

required

Message containing downloadable media

W: DownloadWriter + Send + 'static

required

Writer for streaming output. Must implement DownloadWriter and be Send + ‘static for use in blocking task.

Returns the writer after a successful download, holding exactly the decrypted media and seeked back to position 0 — nothing a caller left in it beforehand, and no tail from a host that failed partway through, survives.

Example: streaming download

use std::fs::File;

let file = File::create("large_video.mp4")?;
let file = client.download_to_writer(video_msg.as_ref(), file).await?;
// File holds exactly the downloaded media, seeked to start, and can be reused

When using an HTTP client that supports streaming (like the default UreqHttpClient), memory usage is constant ~40KB (8KB read buffer + decryption state). HTTP clients that don’t support streaming fall back to buffered downloads, which load the full file into memory before writing.

If the download fails on every host, the writer is emptied too, on a best-effort basis: a sink that refuses to empty is logged rather than replacing the download’s own error. This only matters to a caller who kept a separate handle to the writer (e.g. a shared/cloneable writer), since download_to_writer otherwise consumes it and returns nothing on failure.

DownloadWriter trait

Breaking change (as of PR #1197): download_to_writer, download_from_params_to_writer, and MediaDownloader::download_to_writer now take W: DownloadWriter instead of W: Write + Seek. std::fs::File, std::io::Cursor<Vec<u8>>, std::io::Cursor<&mut Vec<u8>>, std::io::BufWriter<W: DownloadWriter>, and &mut W where W: DownloadWriter all implement it already, so call sites using those types need no changes. A custom writer type needs one additional method — see below.

download_to_writer needs more than Write + Seek from its sink: it needs to be able to empty it.

pub trait DownloadWriter: std::io::Write + std::io::Seek {
    /// Shorten the sink to `len` bytes, discarding anything beyond it.
    /// Only ever called with a length the sink already reaches.
    fn truncate(&mut self, len: u64) -> std::io::Result<()>;
}

Media is authenticated by a single MAC over the whole ciphertext, so decryption has necessarily streamed plaintext into the writer by the time a forged body is caught, and a retry against the next host may end up writing fewer bytes than the attempt it replaces. Rewinding with seek alone can’t remove bytes that are already there — shortening a sink requires a concrete operation (File::set_len, Vec::truncate) that no std trait exposes. DownloadWriter::truncate names that operation, which is what lets download_to_writer guarantee: exactly the media on success, and empty on failure on a best-effort basis (a sink that refuses to empty during that final cleanup is logged, not treated as fatal — see the note above). Every attempt begins by truncating the writer to 0, which clears its length, and then seeking it to 0, which resets its position — two separate operations that both matter on an append-mode File: appending forces every write to the file’s current end regardless of position, so truncating to 0 is what makes that end (and therefore the next write) land at the start; a bare seek would change the position but not the end, and appending would still write there. On success, download_to_writer performs one further seek(0) after the writer’s own bytes are in place, which is the “seeked back to position 0” postcondition on the returned writer described above.

Built-in implementations

Type	`truncate` behavior
`std::fs::File`	Calls `File::set_len`
`std::io::Cursor<Vec<u8>>`	Calls `Vec::truncate`, saturating rather than failing if `len` doesn’t fit in `usize`
`std::io::Cursor<&mut Vec<u8>>`	Same as above, over the borrowed buffer
`std::io::BufWriter<W: DownloadWriter>`	Flushes first (buffered bytes count toward the sink’s length), then delegates to the inner writer
`&mut W where W: DownloadWriter`	Delegates to the wrapped writer

Implementing DownloadWriter for a custom writer

Any writer type used with download_to_writer that isn’t one of the built-ins above — including a wrapper around one, like a progress-reporting adapter — needs its own DownloadWriter impl. For a wrapper, this is normally a one-line delegation:

use wacore::download::DownloadWriter;

impl<W: DownloadWriter> DownloadWriter for ProgressWriter<W> {
    fn truncate(&mut self, len: u64) -> std::io::Result<()> {
        self.inner.truncate(len)
    }
}

See Streaming with Progress for the full ProgressWriter example, including its Write and Seek impls.

download_from_params

Download and decrypt media from raw CDN parameters without the original message. The parameters are bundled into a DownloadParams struct.

pub async fn download_from_params(
    &self,
    params: &DownloadParams,
) -> Result<Vec<u8>, anyhow::Error>

&DownloadParams

required

The CDN/crypto fields needed to fetch and decrypt the media. Build one with DownloadParams::encrypted.

Vec<u8>

Decrypted media bytes

Example: download from stored metadata

use wacore::download::MediaType;
use whatsapp_rust::download::DownloadParams;

// If you stored media metadata separately
let params = DownloadParams::encrypted(
    "/v/t62.7118-24/12345_67890",
    &media_key,
    &file_sha256,
    &file_enc_sha256,
    file_length,
    MediaType::Image,
);

let image_bytes = client.download_from_params(&params).await?;

DownloadParams implements Downloadable, so you can also pass it straight to download: client.download(&params).await?.

download_from_params_to_writer

Streaming variant of download_from_params that writes to a writer. Same writer contract as download_to_writer: the writer must implement DownloadWriter, and holds exactly the decrypted media on success.

pub async fn download_from_params_to_writer<W: DownloadWriter + Send + 'static>(
    &self,
    params: &DownloadParams,
    writer: W,
) -> Result<W, anyhow::Error>

&DownloadParams

required

The CDN/crypto fields needed to fetch and decrypt the media. See DownloadParams.

W: DownloadWriter + Send + 'static

required

Writer for streaming output

Returns the writer after a successful download, holding exactly the decrypted media

DownloadParams

A Downloadable built from raw CDN fields, for re-downloading media without the original message.

pub struct DownloadParams {
    pub direct_path: String,
    pub media_key: Option<Vec<u8>>,
    pub file_sha256: Vec<u8>,
    pub file_enc_sha256: Option<Vec<u8>>,
    pub file_length: u64,
    pub media_type: MediaType,
}

Field	Type	Description
`direct_path`	`String`	WhatsApp CDN path (e.g. `/v/t62.7118-24/12345_67890`)
`media_key`	`Option<Vec<u8>>`	32-byte media key. `None` for plaintext (newsletter/channel) media
`file_sha256`	`Vec<u8>`	SHA-256 of the decrypted file
`file_enc_sha256`	`Option<Vec<u8>>`	SHA-256 of the encrypted file (encrypted media only)
`file_length`	`u64`	Original file size in bytes
`media_type`	`MediaType`	`Image`, `Video`, `Audio`, `Document`, `Sticker`, …

DownloadParams::encrypted

Convenience constructor for encrypted (E2EE) media — fills media_key and file_enc_sha256 as Some(...).

pub fn encrypted(
    direct_path: impl Into<String>,
    media_key: &[u8],
    file_sha256: &[u8],
    file_enc_sha256: &[u8],
    file_length: u64,
    media_type: MediaType,
) -> Self

DownloadParams implements Downloadable, so it works with download, download_to_writer, download_from_params, download_from_params_to_writer, and MediaDownloader.

MediaDownloader

Downloads and decrypts media from the CDN with no connected Client. Everything a download needs beyond the CDN hosts already lives in the Downloadable itself — MediaDownloader takes the hosts (and, optionally, an auth token) up front instead of asking a live session for them, so a persisted reference (for example a stored DownloadParams) stays downloadable after the client has disconnected. A live Client still needs a session to fetch its hosts (cached and refreshed automatically, not re-fetched on every call — see Automatic retry and URL re-derivation); MediaDownloader is the path for callers that have no session to ask with at all — a background worker, a queue consumer, or a CLI tool operating on data a paired client saved earlier.

pub struct MediaDownloader { /* private fields */ }

impl MediaDownloader {
    pub fn new(
        http_client: Arc<dyn HttpClient>,
        runtime: Arc<dyn Runtime>,
        route: MediaRoute,
    ) -> Self;

    pub fn with_default_hosts(
        http_client: Arc<dyn HttpClient>,
        runtime: Arc<dyn Runtime>,
    ) -> Self;

    pub fn route(&self) -> &MediaRoute;

    pub async fn download(
        &self,
        downloadable: &dyn Downloadable,
    ) -> Result<Vec<u8>, MediaDownloadError>;

    pub async fn download_to_writer<W: DownloadWriter + Send + 'static>(
        &self,
        downloadable: &dyn Downloadable,
        writer: W,
    ) -> Result<W, MediaDownloadError>;
}

Arc<dyn HttpClient>

required

The same HttpClient implementation you pass to ClientBuilder. See HTTP Client Trait.

Arc<dyn Runtime>

required

Runtime abstraction used to run blocking decrypt/streaming work.

MediaRoute

required

The CDN hosts to try, in order, and an optional auth token. See MediaRoute below.

download and download_to_writer mirror Client::download and Client::download_to_writer — same streaming/buffered branching, same retry-on-another-host behavior across the route’s hosts, same writer contract for the streaming variant. The one difference is the auth-refresh budget: a Client gets one retry with freshly fetched credentials after an auth or not-found error; MediaDownloader has no session to refresh credentials from, so that class of error is terminal on the first attempt.

Example: download after the session is gone

use std::sync::Arc;
use wacore::download::MediaType;
use whatsapp_rust::download::{DownloadParams, MediaDownloader};

// Needs only an HttpClient + Runtime — no paired Client required.
let downloader = MediaDownloader::with_default_hosts(http_client.clone(), runtime.clone());

// `params` came from CDN fields you saved to your own store earlier, while
// the client was still connected. (`PersistenceManager` covers device/session
// state only — it doesn't store message metadata like this for you.)
let params = DownloadParams::encrypted(
    "/v/t62.7118-24/12345_67890",
    &media_key,
    &file_sha256,
    &file_enc_sha256,
    file_length,
    MediaType::Image,
);

let bytes = downloader.download(&params).await?;

with_default_hosts routes through DEFAULT_MEDIA_HOSTS with no auth token, which matches how WhatsApp Web’s own download URL builder works — auth is an upload concern, not a download one. Pass an explicit MediaRoute to new if you need specific hosts or want to carry a token you obtained another way.

MediaDownloadError

#[non_exhaustive]
pub enum MediaDownloadError {
    ReferenceRejected(anyhow::Error),
    HostsUnreachable(anyhow::Error),
    NoHosts,
    Other(anyhow::Error),
}

Variant	Meaning
`ReferenceRejected`	The CDN rejected the request with 401/403/404/410. On a route built with `MediaRoute::authenticated`, a 401/403 can mean only the auth token is stale — downloads don’t strictly need one, so retrying with `route.without_auth()` before giving up can still succeed. A 404/410, or a 401/403 on an already-unauthenticated route, means the `direct_path` itself is expired or revoked and no host can serve it — that case is terminal.
`HostsUnreachable`	Every host in the route failed for a reason other than the reference (transport failure, unexpected status, a body that failed to decrypt/verify).
`NoHosts`	The `MediaRoute` named no hosts, so nothing was ever contacted.
`Other`	The `Downloadable` didn’t have the fields needed to build a request at all (e.g. no `direct_path` and no `static_url`), so — unlike `NoHosts` — no host was ever going to be contacted. Fix the metadata, not the network.

MediaDownloadError is #[non_exhaustive]; match it with a wildcard (_ => ) arm so a future variant doesn’t break your build. Client::download and Client::download_to_writer keep returning anyhow::Error: they already try a credential refresh before the error would escape, so the extra classification has nothing left to add there.

MediaRoute and MediaHost

MediaRoute replaces the old MediaConnection type — it is the low-level input to DownloadUtils::prepare_download_requests and to MediaDownloader. Where MediaConnection required an auth: String, MediaRoute makes it auth: Option<String>, because the CDN gates a download on the signed direct_path and its hash token, not on a session credential.

pub struct MediaHost {
    pub hostname: String,
}

impl MediaHost {
    pub fn new(hostname: impl Into<String>) -> Self;
}

pub struct MediaRoute {
    pub hosts: Vec<MediaHost>,
    pub auth: Option<String>,
}

impl MediaRoute {
    pub fn authenticated(hosts: Vec<MediaHost>, auth: String) -> Self;
    pub fn unauthenticated(hosts: Vec<MediaHost>) -> Self;
    pub fn without_auth(self) -> Self;
    pub fn default_hosts() -> Self;
}

pub const DEFAULT_MEDIA_HOSTS: [&str; 2] = ["mmg.whatsapp.net", "mmg-fallback.whatsapp.net"];

Constructor	Use when
`MediaRoute::authenticated(hosts, auth)`	You have both server-provided hosts and a media auth token (what a connected `Client` builds from its `MediaConn`).
`MediaRoute::unauthenticated(hosts)`	You have hosts but no token — the common case for `MediaDownloader`.
`route.without_auth()`	You have an authenticated route but want to keep using it past the token’s lifetime; drops the token rather than sending a stale one.
`MediaRoute::default_hosts()`	You have neither — routes through `DEFAULT_MEDIA_HOSTS`, the CDN hosts WhatsApp Web itself carries in its binary-protocol token dictionary. This is only a convenience: a live session should still take its hosts from the server, which is what lets a test harness point downloads at itself.

MediaRoute’s Debug implementation is hand-written to print auth: Some("<redacted>") / auth: None instead of the token itself, so a stray {:?} or tracing field can’t leak a live credential into a log.

Breaking change (as of PR #1194): wacore::download::MediaConnection ({ hosts: Vec<MediaHost>, auth: String }) no longer exists. If you built one directly and passed it to DownloadUtils::prepare_download_requests, migrate by constructing the equivalent MediaRoute in its place: MediaRoute::authenticated(hosts, auth). (The From<&MediaConn> for MediaRoute impl is unrelated to this migration — it converts whatsapp_rust’s own mediaconn::MediaConn, the server response a connected Client refreshes internally, and is what Client::prepare_requests uses under the hood.) Client::download and friends are unaffected either way; this only touches callers using the lower-level DownloadUtils type directly.

fetch_sticker_pack

Fetch first-party sticker pack metadata (and the per-sticker download handles) from the WhatsApp CDN.

pub async fn fetch_sticker_pack(
    &self,
    pack_id: &str,
    locale: &str,
) -> Result<wacore::sticker_pack::StickerPack>

&str

required

The first-party sticker pack ID (typically extracted from a received sticker_pack_message).

&str

required

BCP-47 locale tag for localized name / publisher strings. Pass "en" to match whatsmeow’s default.

StickerPack

Pack metadata plus a Vec<StickerPackItem> of individual stickers. Each StickerPackItem implements Downloadable, so you can pass it straight to client.download(...).

Under the hood the client GETs https://static.whatsapp.net/sticker?lottie=1&cat=sticker_pack_data&id={pack_id}&lg={locale}, parses the JSON envelope, and constructs the StickerPack. The endpoint is unauthenticated — the call works whether or not you are paired. A non-2xx response fails with the same contract as download: the status is recoverable via ErrorChainExt::http_status() (added in PR #1195), not only by parsing the error message.

use whatsapp_rust::Client;

let pack = client.fetch_sticker_pack("3F9Z2…", "en").await?;
println!("Pack '{}' by {}", pack.name, pack.publisher);
for sticker in &pack.stickers {
    let bytes = client.download(sticker).await?;
    std::fs::write(format!("{}.webp", sticker.file_name), bytes)?;
}

StickerPack

pub struct StickerPack {
    pub sticker_pack_id: String,
    pub name: String,
    pub publisher: String,
    pub description: Option<String>,
    pub tray_image_file_name: Option<String>,
    pub stickers: Vec<StickerPackItem>,
    // additional CDN metadata: animated, tray-icon colors, …
}

StickerPackItem

pub struct StickerPackItem {
    pub file_name: String,
    pub emojis: Vec<String>,
    pub accessibility_text: Option<String>,
    pub is_animated: bool,
    // plus all Downloadable fields:
    //   direct_path, media_key, file_enc_sha256, file_sha256, file_length
}

impl Downloadable for StickerPackItem { /* … */ }

The CDN response is a JSON envelope, not a protobuf message — StickerPack / StickerPackItem live in wacore::sticker_pack and are independent of waproto::whatsapp::StickerPackMessage (which represents the inline pack-bubble in a chat). The struct mirrors whatsmeow’s FirstPartyStickerPack.

Downloadable Trait

The Downloadable trait provides a generic interface for downloading media from any message type.

pub trait Downloadable: Sync + Send {
    fn direct_path(&self) -> Option<&str>;
    fn media_key(&self) -> Option<&[u8]>;
    fn file_enc_sha256(&self) -> Option<&[u8]>;
    fn file_sha256(&self) -> Option<&[u8]>;
    fn file_length(&self) -> Option<u64>;
    fn app_info(&self) -> MediaType;
    fn static_url(&self) -> Option<&str> { None }
    fn is_encrypted(&self) -> bool { self.media_key().is_some() }
}

fn() -> Option<&str>

WhatsApp CDN path for the media file

fn() -> Option<&[u8]>

32-byte encryption key. Present for E2EE media, None for plaintext (newsletter/channel) media.

fn() -> Option<&[u8]>

SHA-256 hash of the encrypted file. Used for encrypted media validation.

fn() -> Option<&[u8]>

SHA-256 hash of the decrypted file. Used for plaintext media validation.

fn() -> Option<u64>

Original file size in bytes

fn() -> MediaType

Media type for HKDF key derivation (Image, Video, Audio, Document, etc.)

fn() -> Option<&str>

default:"None"

Static CDN URL for direct download. Present on newsletter/channel media, bypasses host construction.

fn() -> bool

default:"media_key().is_some()"

Returns true if media is encrypted (has media_key), false for plaintext media

Built-in Implementations

The Downloadable trait is automatically implemented for:

wa::message::ImageMessage
wa::message::VideoMessage
wa::message::AudioMessage
wa::message::DocumentMessage
wa::message::StickerMessage
wa::ExternalBlobReference (app state)
wa::message::HistorySyncNotification

MediaType

Media type enum for encryption/decryption.

pub enum MediaType {
    Image,
    Video,
    Audio,
    Document,
    History,
    AppState,
    Sticker,
    StickerPack,
    StickerPackThumbnail,
    LinkThumbnail,
    ProductCatalogImage,
}

Each media type has specific HKDF info strings used for key derivation:

Image / Sticker → "WhatsApp Image Keys"
Video → "WhatsApp Video Keys"
Audio → "WhatsApp Audio Keys"
Document → "WhatsApp Document Keys"
History → "WhatsApp History Keys"
AppState → "WhatsApp App State Keys"
StickerPack → "WhatsApp Sticker Pack Keys"
StickerPackThumbnail → "WhatsApp Sticker Pack Thumbnail Keys"
LinkThumbnail → "WhatsApp Link Thumbnail Keys"

MediaType methods

Method	Return type	Description
`app_info()`	`&'static str`	HKDF info string for key derivation
`mms_type()`	`&'static str`	Media type string for MMS path construction
`upload_path()`	`&'static str`	URL path prefix for upload/download
`is_encrypted()`	`bool`	Whether this media type uses E2E encryption

Upload paths

Media type	Upload path
`Image` / `Sticker`	`/mms/image`
`Video`	`/mms/video`
`Audio`	`/mms/audio`
`Document`	`/mms/document`
`History`	`/mms/md-msg-hist`
`AppState`	`/mms/md-app-state`
`StickerPack`	`/mms/sticker-pack`
`StickerPackThumbnail`	`/mms/thumbnail-sticker-pack`
`LinkThumbnail`	`/mms/thumbnail-link`
`ProductCatalogImage`	`/product/image`

ProductCatalogImage is unencrypted — is_encrypted() returns false. This matches WhatsApp Web’s behavior where CreateMediaKeys.js skips encryption for product catalog images. Its upload path is /product/image (not under the /mms/ prefix like other media types).

Media Decryption

WhatsApp uses different handling for encrypted (E2EE) and plaintext media:

Encrypted Media (E2EE)

Download encrypted bytes from CDN
Verify HMAC-SHA256 (last 10 bytes)
Decrypt using AES-256-CBC with keys derived from media_key via HKDF
Return decrypted plaintext

The media_key is expanded using HKDF-SHA256 to derive:

16-byte IV
32-byte cipher key
32-byte MAC key

Download plaintext bytes from CDN (often via static_url)
Verify SHA-256 hash matches file_sha256
Return plaintext (no decryption needed)

Newsletter and channel media is not encrypted. The library automatically detects this when media_key is absent and switches to plaintext validation.

Example: detect media type

if downloadable.is_encrypted() {
    println!("E2EE media - will decrypt");
} else {
    println!("Plaintext media - no decryption needed");
}

DownloadUtils

Low-level static methods for media decryption and validation. These are re-exported from wacore::download and useful when you need fine-grained control over the download pipeline.

use whatsapp_rust::download::DownloadUtils;

Key methods

Method	Description
`verify_and_decrypt(encrypted_payload, media_key, media_type)`	Verifies HMAC and decrypts AES-256-CBC in one call
`verify_and_decrypt_in_place(encrypted_payload, media_key, media_type)`	In-place counterpart to `verify_and_decrypt` — authenticates and decrypts into the same buffer, truncating the trailing MAC/padding, instead of allocating a separate output. Used internally by non-streaming downloads to avoid keeping two file-sized buffers alive at once
`decrypt_stream(reader, media_key, media_type)`	Streaming decryption from a reader (convenience wrapper around `decrypt_stream_to_writer`)
`decrypt_stream_to_writer(reader, media_key, media_type, writer)`	Streaming decryption directly into a writer with constant memory usage
`validate_plaintext_sha256(data, expected_sha256)`	Validates SHA-256 hash of plaintext media (in-memory)
`copy_and_validate_plaintext_to_writer(reader, expected_sha256, writer)`	Streams plaintext media to a writer while validating SHA-256 hash
`prepare_download_requests(downloadable, route)`	Builds CDN request URLs with host failover. Takes a `MediaRoute` (previously `MediaConnection`) — hosts plus an optional auth token
`get_media_keys(media_key, app_info)`	Derives IV, cipher key, and MAC key via HKDF

Core

Messaging

Features

Storage & Backends

Core Modules

download

download

Example: download image

Example: download with error handling

Recovering the CDN status by type

Automatic retry and URL re-derivation

download_to_writer

Example: streaming download

DownloadWriter trait

Built-in implementations

Implementing DownloadWriter for a custom writer

download_from_params

Example: download from stored metadata

download_from_params_to_writer

DownloadParams

DownloadParams::encrypted

MediaDownloader

Example: download after the session is gone

MediaDownloadError

MediaRoute and MediaHost

fetch_sticker_pack

StickerPack

StickerPackItem

Downloadable Trait

Built-in Implementations

MediaType

MediaType methods

Upload paths

Media Decryption

Encrypted Media (E2EE)

Example: detect media type

DownloadUtils

Key methods

​download

​Example: download image

​Example: download with error handling

​Recovering the CDN status by type

​Automatic retry and URL re-derivation

​download_to_writer

​Example: streaming download

​DownloadWriter trait

​Built-in implementations

​Implementing DownloadWriter for a custom writer

​download_from_params

​Example: download from stored metadata

​download_from_params_to_writer

​DownloadParams

​DownloadParams::encrypted

​MediaDownloader

​Example: download after the session is gone

​MediaDownloadError

​MediaRoute and MediaHost

​fetch_sticker_pack

​StickerPack

​StickerPackItem

​Downloadable Trait

​Built-in Implementations

​MediaType

​MediaType methods

​Upload paths

​Media Decryption

​Encrypted Media (E2EE)

​Plaintext media (newsletter/channel)

​Example: detect media type

​DownloadUtils

​Key methods

download

Example: download image

Example: download with error handling

Recovering the CDN status by type

Automatic retry and URL re-derivation

download_to_writer

Example: streaming download

DownloadWriter trait

Built-in implementations

Implementing DownloadWriter for a custom writer

download_from_params

Example: download from stored metadata

download_from_params_to_writer

DownloadParams

DownloadParams::encrypted

MediaDownloader

Example: download after the session is gone

MediaDownloadError

MediaRoute and MediaHost

fetch_sticker_pack

StickerPack

StickerPackItem

Downloadable Trait

Built-in Implementations

MediaType

MediaType methods

Upload paths

Media Decryption

Encrypted Media (E2EE)

Plaintext media (newsletter/channel)

Example: detect media type

DownloadUtils

Key methods