upload

Upload media to WhatsApp’s CDN with automatic encryption.

Only use upload for new or modified media. To forward existing media unchanged, reuse the original message’s CDN fields directly — no upload required. See media forwarding via CDN reuse.

pub async fn upload(
    &self,
    data: Vec<u8>,
    media_type: MediaType,
    options: UploadOptions,
) -> Result<UploadResponse, anyhow::Error>

Vec<u8>

required

Raw media bytes to upload. The data is automatically encrypted using AES-256-CBC before uploading.

MediaType

required

Type of media being uploaded. Determines the CDN endpoint and encryption keys:

MediaType::Image - Images and stickers
MediaType::Video - Video files
MediaType::Audio - Audio files and voice notes
MediaType::Document - Documents and other files
MediaType::Sticker - Sticker images
MediaType::StickerPack - Sticker pack ZIP files
MediaType::StickerPackThumbnail - Sticker pack thumbnail images
MediaType::LinkThumbnail - Link preview thumbnails
MediaType::ProductCatalogImage - Product catalog images (unencrypted)

UploadOptions

required

Upload options. Use Default::default() or UploadOptions::new() for default behavior. See UploadOptions below.

struct

Contains all metadata needed to include the media in a message:

#[non_exhaustive]
pub struct UploadResponse {
    pub url: String,
    pub direct_path: String,
    pub media_key: [u8; 32],
    pub file_enc_sha256: [u8; 32],
    pub file_sha256: [u8; 32],
    pub file_length: u64,
    pub media_key_timestamp: i64,
    /// Per-64-KiB HMAC sidecar for progressive playback/seek (audio/video
    /// only). Pass to `AudioMessage`/`VideoMessage.streaming_sidecar`.
    pub streaming_sidecar: Option<Vec<u8>>,
}

Helper methods are provided for protobuf message construction, which requires Vec<u8>:

impl UploadResponse {
    pub fn media_key_vec(&self) -> Vec<u8> { ... }
    pub fn file_sha256_vec(&self) -> Vec<u8> { ... }
    pub fn file_enc_sha256_vec(&self) -> Vec<u8> { ... }
}

UploadResponse is #[non_exhaustive]. Field reads are unaffected; only exhaustive struct destructuring from outside the crate requires adding ...

String

Full CDN URL where the encrypted file was uploaded

String

CDN path component (e.g., /v/t62.7118-24/12345_67890). Used for downloads.

[u8; 32]

32-byte encryption key. Required for the recipient to decrypt the media. Use media_key_vec() when building protobuf messages.

[u8; 32]

SHA-256 hash of the encrypted file. Used for integrity verification during download. Use file_enc_sha256_vec() when building protobuf messages.

[u8; 32]

SHA-256 hash of the original (decrypted) file. Used for final validation after decryption. Use file_sha256_vec() when building protobuf messages.

u64

Original file size in bytes (before encryption)

i64

Unix timestamp (seconds) when the media key was generated. Set automatically by upload() to the current time.

Option<Vec<u8>>

Per-64-KiB HMAC-SHA256 table over the ciphertext that lets recipients seek and stream audio/video progressively without downloading the whole file. Generated automatically for audio and video uploads (None otherwise). Assign it to AudioMessage.streaming_sidecar / VideoMessage.streaming_sidecar when building the message. Opt in/out explicitly with UploadOptions::with_streaming_sidecar(bool).

Example: upload and send image

use wacore::download::MediaType;
use waproto::whatsapp as wa;
use std::fs;

// Read image file
let image_bytes = fs::read("photo.jpg")?;

// Upload image to WhatsApp CDN
let upload = client.upload(image_bytes, MediaType::Image, Default::default()).await?;

// Create image message with upload metadata
let message = wa::Message {
    image_message: buffa::MessageField::some(wa::message::ImageMessage {
        url: Some(upload.url),
        direct_path: Some(upload.direct_path),
        media_key: Some(upload.media_key_vec()),
        file_enc_sha256: Some(upload.file_enc_sha256_vec()),
        file_sha256: Some(upload.file_sha256_vec()),
        file_length: Some(upload.file_length),
        media_key_timestamp: Some(upload.media_key_timestamp),
        caption: Some("Check out this photo!".to_string()),
        mimetype: Some("image/jpeg".to_string()),
        ..Default::default()
    }),
    ..Default::default()
};

// Send the message
let result = client.send_message(chat_jid, message).await?;
println!("Image sent: {}", result.message_id);

Example: upload video with progress

use wacore::download::MediaType;
use std::fs;

let video_bytes = fs::read("video.mp4")?;
println!("Uploading {} bytes...", video_bytes.len());

let upload = client.upload(video_bytes, MediaType::Video, Default::default()).await?;
println!("Upload complete!");
println!("  URL: {}", upload.url);
println!("  Path: {}", upload.direct_path);

// Use upload metadata in VideoMessage...

Example: upload document

use wacore::download::MediaType;
use waproto::whatsapp as wa;
use std::fs;
use std::path::Path;

let doc_path = Path::new("report.pdf");
let doc_bytes = fs::read(doc_path)?;
let filename = doc_path.file_name()
    .and_then(|n| n.to_str())
    .unwrap_or("document.pdf");

let upload = client.upload(doc_bytes, MediaType::Document, Default::default()).await?;

let message = wa::Message {
    document_message: buffa::MessageField::some(wa::message::DocumentMessage {
        url: Some(upload.url),
        direct_path: Some(upload.direct_path),
        media_key: Some(upload.media_key_vec()),
        file_enc_sha256: Some(upload.file_enc_sha256_vec()),
        file_sha256: Some(upload.file_sha256_vec()),
        file_length: Some(upload.file_length),
        media_key_timestamp: Some(upload.media_key_timestamp),
        file_name: Some(filename.to_string()),
        mimetype: Some("application/pdf".to_string()),
        ..Default::default()
    }),
    ..Default::default()
};

let result = client.send_message(chat_jid, message).await?;

Example: upload audio (voice note)

use wacore::download::MediaType;
use waproto::whatsapp as wa;

let audio_bytes = fs::read("voice.ogg")?;
let upload = client.upload(audio_bytes, MediaType::Audio, Default::default()).await?;

let message = wa::Message {
    audio_message: buffa::MessageField::some(wa::message::AudioMessage {
        url: Some(upload.url),
        direct_path: Some(upload.direct_path),
        media_key: Some(upload.media_key_vec()),
        file_enc_sha256: Some(upload.file_enc_sha256_vec()),
        file_sha256: Some(upload.file_sha256_vec()),
        file_length: Some(upload.file_length),
        media_key_timestamp: Some(upload.media_key_timestamp),
        mimetype: Some("audio/ogg; codecs=opus".to_string()),
        ptt: Some(true), // Mark as Push-To-Talk (voice note)
        ..Default::default()
    }),
    ..Default::default()
};

let result = client.send_message(chat_jid, message).await?;

High-level message builders

The whatsapp_rust::media module turns an UploadResponse into a ready-to-send wa::Message, so you don’t hand-assemble the CDN/crypto fields (url, direct_path, media_key, file_sha256, file_enc_sha256, file_length, media_key_timestamp, streaming_sidecar) on every send. Each builder takes the upload result plus a typed options struct with sensible MIME defaults.

use wacore::download::MediaType;
use whatsapp_rust::media::{self, ImageOptions, VideoOptions, AudioOptions, DocumentOptions};
use std::fs;

let chat_jid: Jid = "15551234567@s.whatsapp.net".parse()?;
let image_bytes = fs::read("photo.jpg")?;

let upload = client.upload(image_bytes, MediaType::Image, Default::default()).await?;
let msg = media::image_message(upload, ImageOptions {
    caption: Some("Check out this photo!".to_string()),
    ..Default::default()
});
client.send_message(chat_jid, msg).await?;

Builder	Options struct	Notable fields (all optional)	MIME default
`media::image_message(upload, opts)`	`ImageOptions`	`caption`, `mimetype`, `jpeg_thumbnail`	`image/jpeg`
`media::video_message(upload, opts)`	`VideoOptions`	`caption`, `mimetype`, `jpeg_thumbnail`, `duration_seconds`, `gif_playback`	`video/mp4`
`media::document_message(upload, opts)`	`DocumentOptions`	`mimetype`, `file_name`, `title`, `caption`, `page_count`, `jpeg_thumbnail`	`application/octet-stream`
`media::audio_message(upload, opts)`	`AudioOptions`	`mimetype`, `duration_seconds`, `ptt`, `waveform`	`audio/ogg; codecs=opus`

The video_message and audio_message builders carry the upload’s streaming_sidecar (progressive-playback HMAC table) when present. For fields the options structs don’t expose (e.g. explicit image width/height), assemble the proto by hand as shown above.

use wacore::download::MediaType;
use whatsapp_rust::media::{self, AudioOptions};
use std::fs;

// Voice note (push-to-talk) with a waveform preview
let opus_bytes = fs::read("voice.ogg")?;
let waveform_bytes: Vec<u8> = vec![]; // optional PCM waveform preview

let upload = client.upload(opus_bytes, MediaType::Audio, Default::default()).await?;
let msg = media::audio_message(upload, AudioOptions {
    ptt: Some(true),
    duration_seconds: Some(8),
    waveform: Some(waveform_bytes),
    ..Default::default()
});
client.send_message(chat_jid, msg).await?;

UploadOptions

Options for customizing upload behavior.

#[non_exhaustive]
pub struct UploadOptions {
    /// Reuse an existing media key instead of generating a fresh one.
    pub media_key: Option<[u8; 32]>,
    /// Override streaming-sidecar generation; `None` selects by media type.
    pub streaming_sidecar: Option<bool>,
}

UploadOptions is #[non_exhaustive], so it cannot be constructed using struct literal syntax from outside the crate. Use UploadOptions::default() or UploadOptions::new() with builder methods instead.

Option<[u8; 32]>

default:"None"

When set, reuses the provided 32-byte media key instead of generating a new one. This is required when uploading a sticker pack thumbnail, which must share the same media_key as the sticker pack ZIP.

Option<bool>

default:"None"

Override streaming-sidecar generation. None (default) generates the per-64-KiB HMAC-SHA256 streaming_sidecar only for audio and video; Some(true) forces it on; Some(false) forces it off. When produced, assign the resulting UploadResponse.streaming_sidecar to AudioMessage.streaming_sidecar / VideoMessage.streaming_sidecar so recipients can seek and stream progressively.

Creating options

use whatsapp_rust::upload::UploadOptions;

// Default options (generates a new media key)
let options = UploadOptions::default();

// Reuse an existing media key
let options = UploadOptions::new().with_media_key(existing_key.clone());

// Force the streaming sidecar on (e.g. for a media type it skips by default)
let options = UploadOptions::new().with_streaming_sidecar(true);

Example: Upload sticker pack thumbnail with shared key

use whatsapp_rust::upload::UploadOptions;
use wacore::download::MediaType;

// Upload the sticker pack ZIP first
let zip_upload = client.upload(
    zip_bytes,
    MediaType::StickerPack,
    UploadOptions::default(),
).await?;

// Upload the thumbnail with the same media_key
let thumb_upload = client.upload(
    thumbnail_jpeg,
    MediaType::StickerPackThumbnail,
    UploadOptions::new().with_media_key(zip_upload.media_key),
).await?;

MediaEncryptor

Chunk-based AES-256-CBC media encryptor. Processes plaintext incrementally without requiring a sync Read, enabling use with async streams, network sources, or any chunk-at-a-time producer. Two output modes with zero duplicated crypto logic:

update() / finalize() — append encrypted blocks to a Vec<u8>
update_to_writer() / finalize_to_writer() — write to any Write implementor you provide, batching output into ~8 KiB runs internally rather than staging the whole file

pub struct MediaEncryptor { /* ... */ }

Creating an encryptor

use wacore::upload::MediaEncryptor;
use wacore::download::MediaType;

// Initialize with a random media key
let enc = MediaEncryptor::new(MediaType::Image)?;

// Or initialize with a caller-supplied key (must be 32 cryptographically random bytes)
let enc = MediaEncryptor::with_key(media_key, MediaType::Image)?;

MediaType

required

Type of media being encrypted. Determines the HKDF info string for key derivation.

[u8; 32]

Caller-supplied 32-byte key for with_key(). Must be cryptographically random — reusing keys breaks confidentiality.

Feeding plaintext

Feed plaintext in arbitrarily sized chunks. All complete blocks in a call are encrypted immediately. Only a trailing partial block (at most 15 bytes) is buffered across your calls. update_to_writer() also batches its ciphertext into ~8 KiB runs before writing, but only within a single call — it flushes everything to your writer before returning, so if you feed it small inputs you still get small, per-call writes rather than full 8 KiB runs. See the memory note below for details.

// Append encrypted blocks to a Vec
let mut encrypted = Vec::new();
enc.update(plaintext_chunk, &mut encrypted);

// Or write encrypted blocks directly to a writer
enc.update_to_writer(plaintext_chunk, &mut writer)?;

&[u8]

required

Plaintext bytes to encrypt. Can be any size — from a single byte to the entire file.

On update_to_writer I/O error, the encryptor state is unspecified — discard it.

Finalizing

Finalize applies PKCS7 padding to the remaining plaintext, encrypts the final block(s), and appends a 10-byte truncated HMAC-SHA256 MAC.

// Finalize to Vec
let info = enc.finalize(&mut encrypted)?;

// Or finalize to writer
let info = enc.finalize_to_writer(&mut writer)?;

struct

Encryption metadata (keys and hashes). The encrypted data was already written via update/finalize calls.

pub struct EncryptedMediaInfo {
    pub media_key: [u8; 32],
    pub file_sha256: [u8; 32],
    pub file_enc_sha256: [u8; 32],
    pub file_length: u64,
}

[u8; 32]

32-byte encryption key for the recipient to decrypt the media

[u8; 32]

SHA-256 hash of the original plaintext, computed on the fly during encryption

[u8; 32]

SHA-256 hash of the encrypted output (ciphertext + MAC)

u64

Original file size in bytes (before encryption)

Example: Chunk-based encryption to Vec

use wacore::upload::MediaEncryptor;
use wacore::download::MediaType;

let mut enc = MediaEncryptor::new(MediaType::Image)?;
let mut encrypted = Vec::new();

// Feed plaintext in arbitrary chunks
for chunk in plaintext_data.chunks(4096) {
    enc.update(chunk, &mut encrypted);
}

let info = enc.finalize(&mut encrypted)?;
println!("Media key: {:?}", info.media_key);
println!("Original size: {} bytes", info.file_length);

Example: Streaming encryption to a writer

use wacore::upload::MediaEncryptor;
use wacore::download::MediaType;
use std::fs::File;

let mut enc = MediaEncryptor::new(MediaType::Video)?;
let mut writer = File::create("large_video.enc")?;

// Feed chunks from any source (async stream, network, etc.)
for chunk in reader_chunks {
    enc.update_to_writer(&chunk, &mut writer)?;
}

let info = enc.finalize_to_writer(&mut writer)?;

The encryptor’s own internal state uses constant memory, regardless of file size, with one exception: the streaming sidecar. When enabled (the default for audio and video), it accumulates a per-64-KiB HMAC table — about 10 bytes per 64 KiB of ciphertext — until finalize()/finalize_to_writer() returns it, so it grows slowly with file size even when your destination is a writer. This also doesn’t cover whatever destination you provide.With update()/finalize(), you’re only buffering the crypto state and at most 15 bytes of remainder plaintext. Your destination Vec itself still grows with the encrypted output.With update_to_writer()/finalize_to_writer(), ciphertext is also staged internally, bounding memory at crypto state + remainder + ~8 KiB. It’s flushed to your writer in ~8 KiB runs rather than once per 16-byte block, amortizing the Write call — but only within a single call, since nothing is held across calls. If you feed it small chunks (e.g. one 16-byte block per call), you still get small, per-call writes rather than 8 KiB runs. Your writer itself (e.g. a File) need not retain anything.Unlike encrypt_media_streaming, MediaEncryptor does not require a sync Read source, making it suitable for async contexts.

Streaming encryption

For sync Read sources, encrypt_media_streaming provides a convenience wrapper around MediaEncryptor that reads in 8KB chunks:

pub fn encrypt_media_streaming<R: Read, W: Write>(
    reader: R,
    writer: W,
    media_type: MediaType,
) -> Result<EncryptedMediaInfo>

R: Read

required

Source of plaintext media bytes. Can be a File, Cursor<Vec<u8>>, or any Read implementor.

W: Write

required

Destination for encrypted output. Receives ciphertext + 10-byte HMAC-SHA256 MAC — the exact bytes to upload to WhatsApp CDN.

MediaType

required

Type of media being encrypted. Determines the HKDF info string for key derivation.

Example: Encrypt from file to file

use wacore::upload::encrypt_media_streaming;
use wacore::download::MediaType;
use std::fs::File;

let reader = File::open("large_video.mp4")?;
let writer = File::create("large_video.enc")?;

let info = encrypt_media_streaming(reader, writer, MediaType::Video)?;
println!("Media key: {:?}", info.media_key);
println!("Original size: {} bytes", info.file_length);

encrypt_media_streaming uses ~40KB of memory regardless of file size (8KB read buffer + crypto state). Internally it creates a MediaEncryptor and feeds 8KB chunks from the reader.

encrypt_media_streaming_with_key

pub fn encrypt_media_streaming_with_key<R: Read, W: Write>(
    reader: R,
    writer: W,
    media_type: MediaType,
    media_key: Option<&[u8; 32]>,
    sidecar: Option<bool>,
) -> Result<EncryptedMediaInfo>

Lower-level variant of encrypt_media_streaming. It returns the same EncryptedMediaInfo (including the optional streaming_sidecar) but lets you control two things the convenience wrapper decides for you:

media_key — pass Some(&key) to encrypt with a pre-existing 32-byte key (e.g. when re-encrypting for a shared-key sticker pack), or None to generate a fresh random key like encrypt_media_streaming does.
sidecar — pass Some(true)/Some(false) to force the streaming sidecar on or off, or None to use the per-media-type default (generated for audio/video).

Reach for this when you need a deterministic key or want to override sidecar generation; otherwise use encrypt_media_streaming, which calls this with None, None.

Relationship to `encrypt_media`

When you call encrypt_media, it forwards through encrypt_media_with_key to encrypt_media_with_key_and_sidecar, which drives MediaEncryptor directly and sizes the output Vec exactly up front via encrypted_len:

pub fn encrypt_media_with_key_and_sidecar(
    plaintext: &[u8],
    media_type: MediaType,
    media_key: Option<&[u8; 32]>,
    sidecar: Option<bool>,
) -> Result<EncryptedMedia> {
    let want_sidecar = sidecar.unwrap_or_else(|| media_type_uses_sidecar(media_type));
    let mut enc = match media_key {
        Some(key) => MediaEncryptor::with_key_and_sidecar(*key, media_type, want_sidecar)?,
        None => MediaEncryptor::new_with_sidecar(media_type, want_sidecar)?,
    };
    let mut data_to_upload = Vec::with_capacity(encrypted_len(plaintext.len()));
    enc.update(plaintext, &mut data_to_upload);
    let info = enc.finalize(&mut data_to_upload)?;
    Ok(EncryptedMedia {
        data_to_upload,
        media_key: info.media_key,
        file_sha256: info.file_sha256,
        file_enc_sha256: info.file_enc_sha256,
        streaming_sidecar: info.streaming_sidecar,
    })
}

data_to_upload used to start from Vec::new() and grow by doubling, so a 16 MiB video reallocated close to a dozen times on its way to 32 MiB of capacity — copying everything encrypted so far on each grow, and peaking (plaintext + old buffer + new buffer) near 64 MiB, about 4x the ~16 MiB ciphertext. encrypted_len (below) gives the exact output size up front, so this path now allocates once, peaking at plaintext + ciphertext ≈ 32 MiB instead.

When to use each API

API	Use when
`MediaEncryptor`	You have an async stream, network source, or need full control over chunk sizes
`encrypt_media_streaming`	You have a sync `Read` source (file, cursor)
`encrypt_media`	The entire plaintext fits in memory

upload_stream (constant-memory)

upload() encrypts the whole plaintext into a Vec<u8> in memory before sending. For large files, upload_stream keeps memory constant by uploading already-encrypted ciphertext from any backing store (temp file, memory-mapped blob, …) without re-buffering it.

pub async fn upload_stream<S>(
    &self,
    source: S,
    info: wacore::upload::EncryptedMediaInfo,
    media_type: MediaType,
) -> Result<UploadResponse>
where
    S: wacore::upload::UploadSource + 'static,

The flow is two steps you own:

Encrypt the plaintext into storage of your choice with encrypt_media_streaming (or encrypt_media_streaming_with_key). It returns an EncryptedMediaInfo carrying the crypto metadata and the optional streaming_sidecar.
Pass that storage (as an UploadSource) plus the EncryptedMediaInfo to upload_stream. The method never touches disk itself.

use wacore::upload::{encrypt_media_streaming, UploadSource};
use wacore::download::MediaType;
use std::fs::File;
use std::io::{Read, Seek, SeekFrom};
use tempfile::NamedTempFile;

// A file-backed UploadSource. It owns the temp file (so the data lives as
// long as the source) and reopens it by path on every attempt, giving each
// reader its own independent OS file offset — safe for retry / resume /
// host-failover, which re-invoke reader_from.
struct FileSource {
    file: NamedTempFile,
    len: u64,
}

impl UploadSource for FileSource {
    fn len(&self) -> u64 {
        self.len
    }
    fn reader_from(&self, offset: u64) -> std::io::Result<Box<dyn Read + Send>> {
        let mut f = File::open(self.file.path())?; // fresh fd, independent cursor
        f.seek(SeekFrom::Start(offset))?;
        Ok(Box::new(f))
    }
}

// 1. Encrypt big_video.mp4 into a named temp file (constant memory). `&File`
//    implements Write, so the ciphertext is written straight to disk.
let cipher_file = NamedTempFile::new()?;
let info = encrypt_media_streaming(
    File::open("big_video.mp4")?,
    cipher_file.as_file(),
    MediaType::Video,
)?;
let len = cipher_file.as_file().metadata()?.len(); // ciphertext size

// 2. Stream the ciphertext straight from the temp file to the CDN — the
//    blob is never buffered in memory.
let source = FileSource { file: cipher_file, len };
let upload = client.upload_stream(source, info, MediaType::Video).await?;

// upload.streaming_sidecar is propagated from the EncryptedMediaInfo.

Don’t back a multi-attempt UploadSource with File::try_clone() — on Unix the cloned descriptor shares the original’s file offset, so a retry or resume that calls reader_from again would move the cursor out from under any concurrent read. Reopen by path (as above) or use positional reads so each reader has an independent offset.

If the ciphertext already fits comfortably in memory, skip the custom source and pass it directly — bytes::Bytes implements UploadSource, so client.upload_stream(bytes::Bytes::from(ciphertext_vec), info, media_type) works for the small-file case. The file-backed source above is what keeps memory constant for large media.

UploadSource trait

upload_stream accepts anything implementing UploadSource:

pub trait UploadSource: Send + Sync {
    /// Total length of the encrypted blob in bytes.
    fn len(&self) -> u64;
    fn is_empty(&self) -> bool { self.len() == 0 }
    /// A reader positioned at `offset`. Called once per upload attempt
    /// (re-invoked on retry / resume).
    fn reader_from(&self, offset: u64) -> std::io::Result<Box<dyn Read + Send>>;
}

Built-in implementations:

Type	Notes
`std::sync::Arc<[u8]>`	In-memory shared buffer
`bytes::Bytes`	O(1) to construct from an owned `Vec<u8>` (adopts the buffer instead of copying). Prefer this when the ciphertext was produced into a `Vec`.

Implement the trait yourself for a file-backed or network-backed source — reader_from(offset) is what makes resumable uploads work without re-encrypting.

encrypted_len

pub const fn encrypted_len(plaintext_len: usize) -> usize

Computes the exact ciphertext size for a given plaintext length (plaintext rounded up to the next 16-byte AES block, plus the 10-byte media MAC). Use it to pre-allocate an exact-fit Vec before streaming encryption, avoiding reallocation as the ciphertext grows.

upload() is unchanged and still the right choice when the plaintext fits in memory — both paths share the same retry/resumable-upload machinery. Reach for upload_stream only when you want to bound memory for large media.

Resumable uploads

For files 5 MiB (5,242,880 bytes) or larger, the client automatically probes the CDN to check for a previous partial or complete upload of the same file before sending the full payload.

Resume check flow

A POST request is sent to the upload URL with ?resume=1 appended
The server responds with one of three states:
- Complete — the file already exists on the CDN. The existing url and direct_path are returned immediately with no upload
- Resume — a partial upload exists. The client resumes from the given byte_offset, appending &file_offset={offset} to the URL and sending only the remaining bytes
- Not found — no previous upload exists. A full upload proceeds normally

The resume check is non-fatal. If the probe request itself fails (network error, unexpected response), the client silently falls back to a full upload. No special handling is needed in your code.

Resume check endpoint

POST https://{media_host}/mms/{type}/{token}?auth={auth}&token={token}&resume=1
Origin: https://web.whatsapp.com

Resumed upload endpoint

When a partial upload is detected at byte offset N:

POST https://{media_host}/mms/{type}/{token}?auth={auth}&token={token}&file_offset=N
Content-Type: application/octet-stream
Body: [encrypted bytes from offset N onward]

Media Encryption

All media uploaded to WhatsApp is end-to-end encrypted before transmission:

Encryption Process

Generate keys: Create random 32-byte media_key
Derive keys: Use HKDF-SHA256 with media type info string to derive:
- 16-byte IV (initialization vector)
- 32-byte cipher key
- 32-byte MAC key
Encrypt: Apply AES-256-CBC with PKCS7 padding
Compute MAC: HMAC-SHA256 over IV + ciphertext, append first 10 bytes
Upload: POST encrypted bytes to WhatsApp CDN
Return metadata: media_key, hashes, and CDN path for message

Key Derivation

Each media type uses a specific HKDF info string:

MediaType::Image              → "WhatsApp Image Keys"
MediaType::Video              → "WhatsApp Video Keys"
MediaType::Audio              → "WhatsApp Audio Keys"
MediaType::Document           → "WhatsApp Document Keys"
MediaType::Sticker            → "WhatsApp Image Keys"
MediaType::StickerPack        → "WhatsApp Sticker Pack Keys"
MediaType::StickerPackThumbnail → "WhatsApp Sticker Pack Thumbnail Keys"
MediaType::LinkThumbnail      → "WhatsApp Link Thumbnail Keys"
MediaType::History            → "WhatsApp History Keys"
MediaType::AppState           → "WhatsApp App State Keys"
MediaType::ProductCatalogImage → N/A (unencrypted)

The media_key is shared with recipients through the encrypted message, allowing them to decrypt the media. ProductCatalogImage is the exception — it is uploaded without encryption and has no media key.

Encryption vs Decryption

The encryption process is the inverse of download decryption:

Upload (Encryption)	Download (Decryption)
Generate `media_key`	Receive `media_key` in message
Derive IV, cipher key, MAC key	Derive same keys from `media_key`
Encrypt with AES-256-CBC	Decrypt with AES-256-CBC
Append HMAC-SHA256 (10 bytes)	Verify HMAC-SHA256
Upload to CDN	Download from CDN

MediaType

Specifies the type of media for encryption and CDN routing.

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

variant

JPEG, PNG, or other image formats. Uses /mms/image endpoint and "WhatsApp Image Keys" for HKDF.

variant

MP4 or other video formats. Uses /mms/video endpoint and "WhatsApp Video Keys" for HKDF.

variant

Audio files and voice notes. Uses /mms/audio endpoint and "WhatsApp Audio Keys" for HKDF.

variant

PDF, DOCX, ZIP, and other document formats. Uses /mms/document endpoint and "WhatsApp Document Keys" for HKDF.

variant

Sticker images (WebP format). Uses /mms/image endpoint and "WhatsApp Image Keys" for HKDF (same as images).

variant

History sync data. Uses /mms/md-msg-hist endpoint and "WhatsApp History Keys" for HKDF.

variant

App state sync data. Uses /mms/md-app-state endpoint and "WhatsApp App State Keys" for HKDF.

variant

Sticker pack ZIP files. Uses /mms/sticker-pack endpoint and "WhatsApp Sticker Pack Keys" for HKDF.

variant

Sticker pack thumbnail images (JPEG). Uses /mms/thumbnail-sticker-pack endpoint and "WhatsApp Sticker Pack Thumbnail Keys" for HKDF. Must be uploaded with the same media_key as the corresponding sticker pack ZIP — use UploadOptions::new().with_media_key(...).

variant

Link preview thumbnails. Uses /mms/thumbnail-link endpoint and "WhatsApp Link Thumbnail Keys" for HKDF.

variant

Product catalog images for WhatsApp Business. Unencrypted — is_encrypted() returns false. Uses /product/image endpoint (not under the /mms/ prefix). Matches WhatsApp Web’s CreateMediaKeys.js behavior which skips encryption for this type.

Upload Endpoint

The upload endpoint is constructed as:

https://{media_host}{upload_path}/{token}?auth={auth}&token={token}

Where:

{media_host} — CDN hostname from media connection (primary hosts tried first)
{upload_path} — Media type path from MediaType::upload_path() (e.g., /mms/image, /mms/video, /product/image)
{token} — Base64url-encoded file_enc_sha256
{auth} — Media connection auth token

Most media types use the /mms/{type} prefix, but ProductCatalogImage uses /product/image directly. The upload_path() method returns the correct path for each media type.

Optional query parameters (added automatically for resumable uploads):

resume=1 — probe for existing upload (resume check request)
file_offset={N} — resume upload from byte offset N

The request uses:

Method: POST
Content-Type: application/octet-stream
Origin: https://web.whatsapp.com
Body: Encrypted media bytes (or remaining bytes when resuming)

The upload automatically handles media connection refresh. If the connection is expired, it’s renewed before uploading. If the CDN returns HTTP 401 or 403, the client invalidates the cached credentials, fetches a fresh auth token, and retries the upload once.

Error Handling

Automatic retry on auth errors

The upload method automatically retries when WhatsApp’s CDN returns HTTP 401 or 403. On an auth error, the client invalidates the cached media connection, fetches fresh credentials from WhatsApp’s servers, and retries the upload once. If the retry also fails with an auth error, the error is returned to the caller. For non-auth HTTP errors (such as 500), the client tries the next available CDN host without refreshing credentials. Hosts are tried in priority order — primary hosts first, then fallback hosts.

Recovering the host’s status by type

As of PR #1195, upload_error_from_response attaches the refusing host’s status as a typed HttpStatusError node, not only into the error message. If every host in the failover list refuses, the status of the last refusal survives into the returned error and is recoverable with ErrorChainExt::http_status() — no string matching required:

use whatsapp_rust::ErrorChainExt;

match client.upload(data, media_type, Default::default()).await {
    Ok(upload) => { /* Success */ }
    Err(e) => {
        let cause: &(dyn std::error::Error + 'static) = e.as_ref();
        match cause.http_status() {
            Some(401) | Some(403) => eprintln!("auth retry already exhausted: {e}"),
            // 500/502/503/504 are the 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!("upload host refused with {status}: {e}"),
            None => eprintln!("no HTTP refusal status recoverable, inspect the cause: {e}"),
        }
    }
}

None doesn’t mean no HTTP exchange took place — only that no refused status was attached to this error. See download’s note on None for the same distinction on the mirrored path.

Common upload errors

error

CDN returned error status. Auth errors (401/403) are retried automatically with fresh credentials. Other errors are tried against alternate CDN hosts.

use whatsapp_rust::ErrorChainExt;

match client.upload(data, media_type, Default::default()).await {
    Err(e) => {
        let cause: &(dyn std::error::Error + 'static) = e.as_ref();
        if let Some(status) = cause.http_status() {
            eprintln!("CDN error {status}: {e}");
            // Retry or use fallback
        } else {
            eprintln!("Other error: {}", e);
        }
    }
    Ok(upload) => { /* Success */ }
}

error

Media connection has no available CDN hosts.

Err(anyhow!("No media hosts"))

error

Failed to encrypt media (rare, usually indicates invalid input).

match client.upload(data, media_type, Default::default()).await {
    Err(e) if e.to_string().contains("encrypt") => {
        eprintln!("Encryption error: {}", e);
    }
    _ => {}
}

Example: Upload with additional retry

Auth errors (401/403) are retried automatically. For other transient failures, you can add your own retry logic:

use std::time::Duration;
use tokio::time::sleep;

let mut attempts = 0;
let max_attempts = 3;

let upload = loop {
    attempts += 1;
    
    match client.upload(data.clone(), MediaType::Image, Default::default()).await {
        Ok(upload) => break upload,
        Err(e) if attempts < max_attempts => {
            eprintln!("Upload attempt {} failed: {}", attempts, e);
            sleep(Duration::from_secs(2)).await;
            continue;
        }
        Err(e) => return Err(e),
    }
};

println!("Upload succeeded after {} attempt(s)", attempts);

​upload

​Example: upload and send image

​Example: upload video with progress

​Example: upload document

​Example: upload audio (voice note)

​High-level message builders

​UploadOptions

​Creating options

​Example: Upload sticker pack thumbnail with shared key

​MediaEncryptor

​Creating an encryptor

​Feeding plaintext

​Finalizing

​Example: Chunk-based encryption to Vec

​Example: Streaming encryption to a writer

​Streaming encryption

​Example: Encrypt from file to file

​encrypt_media_streaming_with_key

​Relationship to encrypt_media

​When to use each API

​upload_stream (constant-memory)

​UploadSource trait

​encrypted_len

​Resumable uploads

​Resume check flow

​Resume check endpoint

​Resumed upload endpoint

​Media Encryption

​Encryption Process

​Key Derivation

​Encryption vs Decryption

​MediaType

​Upload Endpoint

​Error Handling

​Automatic retry on auth errors

​Recovering the host’s status by type

​Common upload errors

​Example: Upload with additional retry

upload

Example: upload and send image

Example: upload video with progress

Example: upload document

Example: upload audio (voice note)

High-level message builders

UploadOptions

Creating options

Example: Upload sticker pack thumbnail with shared key

MediaEncryptor

Creating an encryptor

Feeding plaintext

Finalizing

Example: Chunk-based encryption to Vec

Example: Streaming encryption to a writer

Streaming encryption

Example: Encrypt from file to file

encrypt_media_streaming_with_key

Relationship to `encrypt_media`

When to use each API

upload_stream (constant-memory)

UploadSource trait

encrypted_len

Resumable uploads

Resume check flow

Resume check endpoint

Resumed upload endpoint

Media Encryption

Encryption Process

Key Derivation

Encryption vs Decryption

MediaType

Upload Endpoint

Error Handling

Automatic retry on auth errors

Recovering the host’s status by type

Common upload errors

Example: Upload with additional retry