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>

data

Vec<u8>

required

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

media_type

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)

options

UploadOptions

required

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

UploadResponse

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 ...

url

String

Full CDN URL where the encrypted file was uploaded

direct_path

String

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

media_key

[u8; 32]

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

file_enc_sha256

[u8; 32]

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

file_sha256

[u8; 32]

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

file_length

u64

Original file size in bytes (before encryption)

media_key_timestamp

i64

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

streaming_sidecar

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: Some(Box::new(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: Some(Box::new(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: Some(Box::new(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.

media_key

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.

streaming_sidecar

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 directly to any Write implementor, zero intermediate buffer

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)?;

media_type

MediaType

required

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

media_key

[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. Encrypted AES blocks are emitted as soon as a full 16-byte block is available; partial blocks are buffered internally (at most 15 bytes).

// 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)?;

plaintext

&[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)?;

EncryptedMediaInfo

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,
}

media_key

[u8; 32]

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

file_sha256

[u8; 32]

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

file_enc_sha256

[u8; 32]

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

file_length

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)?;

Memory usage is constant regardless of file size — only the crypto state and at most 15 bytes of remainder are buffered. 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>

reader

R: Read

required

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

writer

W: Write

required

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

media_type

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`

The in-memory encrypt_media function is a convenience wrapper around encrypt_media_streaming:

pub fn encrypt_media(plaintext: &[u8], media_type: MediaType) -> Result<EncryptedMedia> {
    let mut data_to_upload = Vec::new();
    let info = encrypt_media_streaming(Cursor::new(plaintext), &mut data_to_upload, media_type)?;
    Ok(EncryptedMedia {
        data_to_upload,
        media_key: info.media_key,
        file_sha256: info.file_sha256,
        file_enc_sha256: info.file_enc_sha256,
    })
}

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,
}

Image

variant

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

Video

variant

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

Audio

variant

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

Document

variant

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

Sticker

variant

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

History

variant

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

AppState

variant

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

StickerPack

variant

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

StickerPackThumbnail

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(...).

LinkThumbnail

variant

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

ProductCatalogImage

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.

Common upload errors

HTTP 4xx/5xx

error

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

match client.upload(data, media_type, Default::default()).await {
    Err(e) if e.to_string().contains("Upload failed") => {
        eprintln!("CDN error: {}", e);
        // Retry or use fallback
    }
    Err(e) => eprintln!("Other error: {}", e),
    Ok(upload) => { /* Success */ }
}

No media hosts

error

Media connection has no available CDN hosts.

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

Encryption failure

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

​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

Common upload errors

Example: Upload with additional retry