Installation

Prerequisites

Before installing whatsapp-rust, ensure you have:

Rust nightly (default) — required for Rust edition 2024 and SIMD-optimized binary protocol. The project pins nightly-2026-04-05 via rust-toolchain.toml. See Using stable Rust if you need stable toolchain support.
Cargo package manager

SQLite is bundled by default with the whatsapp-rust-sqlite-storage crate, so you don’t need to install it separately. If you prefer to link against a system-installed SQLite, disable the default bundled-sqlite feature.

Add to your project

whatsapp-rust re-exports the entire stack (wacore, wacore_binary, waproto, and all bundled implementations), so one dependency line is enough for most projects:

Cargo.toml

[dependencies]
whatsapp-rust = "0.6"
tokio = { version = "1.48", features = ["macros", "rt-multi-thread"] }

Every sub-crate path is reachable through the main crate:

whatsapp_rust::waproto::whatsapp (aliased as wa in prelude)
whatsapp_rust::wacore, whatsapp_rust::wacore_binary
whatsapp_rust::store::SqliteStore, whatsapp_rust::http::UreqHttpClient, whatsapp_rust::transport::TokioWebSocketTransportFactory

whatsapp-rust also re-exports every third-party crate whose types appear in its public API, so you never need to add or version-pin any of these yourself:

whatsapp_rust::buffa — sub-message fields on wa::Message (MessageField; also re-exported directly from prelude) — see waproto
whatsapp_rust::anyhow — the error type on the store/transport/InboundDurabilityHook traits
whatsapp_rust::async_trait — the macro required to implement those traits
whatsapp_rust::bytes — Transport::send payloads
whatsapp_rust::chrono — timestamps returned by wacore::time and message metadata
whatsapp_rust::futures — the oneshot::Receiver returned by response-waiting accessors
whatsapp_rust::serde, whatsapp_rust::serde_json, whatsapp_rust::async_channel

This is purely additive — you can still add any of these crates directly (for example to pin your own version, or to use APIs beyond what whatsapp-rust re-exports).

The same holds for git consumers — no need to pin every sibling crate:

Cargo.toml

[dependencies]
whatsapp-rust = { git = "https://github.com/oxidezap/whatsapp-rust", rev = "<commit>" }
tokio = { version = "1.48", features = ["macros", "rt-multi-thread"] }

If you need to declare a sibling crate explicitly (for example to enable a crate-specific feature flag), you can still add it individually. The full multi-crate form:

[dependencies]
whatsapp-rust = "0.6"
# Only needed for crate-specific features not exposed through whatsapp-rust:
# whatsapp-rust-sqlite-storage = "0.6"
# whatsapp-rust-tokio-transport = "0.6"
# whatsapp-rust-ureq-http-client = "0.6"
# wacore = "0.6"
# waproto = "0.6"
tokio = { version = "1.48", features = ["macros", "rt-multi-thread"] }

[dependencies]
whatsapp-rust = { version = "0.6", default-features = false, features = [
    "sqlite-storage",
    "tokio-transport",
    "tokio-runtime",
    "ureq-client",
    "tokio-native",
    "signal",
] }
wacore = { version = "0.6", default-features = false }
tokio = { version = "1.48", features = ["macros", "rt-multi-thread"] }

Feature flags

whatsapp-rust supports several optional features:

Feature	Description	Included by default
`tokio-runtime`	Enables `TokioRuntime` implementation of the `Runtime` trait. Also required for `TypedCache::invalidate_all()` on custom cache backends	✅ Yes
`tokio-native`	Multi-threaded Tokio runtime (`tokio/rt-multi-thread`)	✅ Yes
`tokio-transport`	Tokio WebSocket transport	✅ Yes
`ureq-client`	Ureq HTTP client	✅ Yes
`sqlite-storage`	SQLite storage backend	✅ Yes
`simd`	SIMD-optimized binary protocol encoding/decoding (requires nightly Rust)	✅ Yes
`signal`	Unix signal handling (graceful shutdown on SIGTERM/Ctrl+C)	✅ Yes
`tracing`	Emit `tracing` spans/events across connect, send, receive, IQ, app state, pairing, media, and session flows. See Observability	❌ No
`tracing-pii`	Render raw phone numbers in `tracing` fields instead of redacted `pn#<token>`. Local debugging only — never enable in production	❌ No
`metrics`	Emit `wa_*` counters, histograms, and gauges through the `metrics` facade for Prometheus/OTLP dashboards. See Metrics	❌ No
`client-lifecycle`	Low-level, generation-scoped extension lifecycle seam (`ClientLifecycle`, `ConnectionScope`). Enabled automatically by `plugins`; enable it directly only if you need lifecycle hooks without the full native plugin host. Requires git source — not in published 0.6	❌ No
`plugins`	Build-time native plugin host: type-safe `ClientPlugin` registration through `ClientBuilder`, capability-scoped APIs, and generation-scoped task lifecycle. Enables `client-lifecycle`. Requires git source — not in published 0.6 (see Native plugins)	❌ No
`voip`	1:1 voice and video calls, full profile: bundled MLow + libopus codec adapters, codec-neutral H.264 video plane, E2E-SRTP encryption, relay transport. Alias for `voip-mlow` + `voip-libopus`. Requires git source — not in published 0.6 (see VoIP Calls)	❌ No
`voip-runtime`	Internal base feature enabled by every `voip-` feature below (Tokio driver, relay transport, DTLS/SCTP). Not meant to be named directly — pick `voip-encoded` or a codec feature instead. Requires git source — not in published 0.6*	❌ No
`voip-encoded`	Narrower `voip` profile: relay transport and encoded-audio boundary only, no bundled codec — supply raw Opus/MLOW packets from your own encoder/decoder. Requires git source — not in published 0.6	❌ No
`voip-mlow`	`voip-encoded` plus the bundled pure-Rust MLOW codec. Requires git source — not in published 0.6	❌ No
`voip-libopus`	`voip-encoded` plus the optional libopus FFI codec adapter. Requires git source — not in published 0.6	❌ No
`danger-skip-tls-verify`	Skip TLS verification (unsafe)	❌ No
`debug-snapshots`	Debug protocol snapshots	❌ No

All default features enable Tokio as the async runtime, but every component is optional. To target a different runtime (async-std, WASM, etc.), disable all defaults and provide your own implementations of the Runtime, TransportFactory, HttpClient, and Backend traits. See custom backends for details.

The wacore crate has an additional feature for WASM browser targets:

Feature	Description	Included by default
`js`	Enables browser-compatible random number generation via `getrandom/wasm_js` for `wasm32` targets	❌ No

To use whatsapp-rust in a WASM browser environment, enable the js feature on wacore:

Cargo.toml

[dependencies]
wacore = { version = "0.6", default-features = false, features = ["js"] }

The waproto crate has its own feature flags:

Feature	Description	Included by default
`serde-deserialize`	Adds `Deserialize` derive and `#[serde(default)]` to all protobuf types	❌ No
`serde-snake-case`	Accepts snake_case enum variant names during deserialization (implies `serde-deserialize`)	❌ No
`serde-enum-repr`	Enums (de)serialize as their numeric repr instead of the variant name — what the JS/WASM bridge and camelCase serializer expect	❌ No

build.rs always runs and generates whatsapp.rs into OUT_DIR — you do not need any feature flag for normal builds. All protobuf types derive Serialize by default. Enable serde-deserialize when you need to parse protobuf types from JSON (e.g., in a WASM bridge). Enable serde-snake-case when your JSON source uses snake_case for enum variants (buffa generates SCREAMING_SNAKE_CASE by default).

Cargo.toml

[dependencies]
waproto = { version = "0.6", features = ["serde-snake-case"] }

The whatsapp-rust-sqlite-storage crate has its own feature flags:

Feature	Description	Included by default
`bundled-sqlite`	Bundles SQLite (compiles from source, no system library needed)	✅ Yes

To use a system-installed SQLite instead of the bundled version:

Cargo.toml

[dependencies]
whatsapp-rust-sqlite-storage = { version = "0.6", default-features = false }

The optional whatsapp-rust-chat-store crate — an event-sourced SQLite chat/message history store, not re-exported through whatsapp-rust — has its own feature flag:

Feature	Description	Included by default
`search`	SQLite FTS5 full-text message search	❌ No

Cargo.toml

[dependencies]
whatsapp-rust-chat-store = "0.1"

To enable full-text search, turn on the search feature:

Cargo.toml

[dependencies]
whatsapp-rust-chat-store = { version = "0.1", features = ["search"] }

See Chat Store for the full API.

The default features provide everything needed for most use cases. Only customize features if you have specific requirements.

Using stable Rust

By default, whatsapp-rust uses Rust edition 2024 and enables the simd feature, which uses Rust’s portable_simd API for optimized binary protocol encoding/decoding. Both of these require a nightly Rust toolchain. The project pins nightly-2026-04-05 via rust-toolchain.toml. To compile on stable Rust, disable the simd feature by setting default-features = false. You must do this on both whatsapp-rust and wacore — otherwise Cargo’s feature unification will re-enable SIMD through the wacore dependency:

Cargo.toml

[dependencies]
# Disable defaults (removes `simd`), then re-enable everything else
whatsapp-rust = { version = "0.6", default-features = false, features = [
    "sqlite-storage",
    "tokio-transport",
    "tokio-runtime",
    "ureq-client",
    "tokio-native",
    "signal",
] }
# wacore also needs default-features = false to prevent feature unification
# from re-enabling simd
wacore = { version = "0.6", default-features = false }

# These crates have no SIMD dependency — no changes needed
whatsapp-rust-sqlite-storage = "0.6"
whatsapp-rust-tokio-transport = "0.6"
whatsapp-rust-ureq-http-client = "0.6"
waproto = "0.6"
tokio = { version = "1.48", features = ["macros", "rt-multi-thread"] }

Setting default-features = false only on whatsapp-rust is not enough if you also depend on wacore directly. The direct wacore dependency enables simd by default, and Cargo merges features across all dependents. Both must opt out.

The encoder/decoder automatically falls back to scalar code paths when SIMD is disabled. There is no functional difference — only a minor performance difference in binary protocol operations.

32-bit target support

whatsapp-rust uses portable-atomic instead of std::sync::atomic for 64-bit atomic operations. This means the library works on 32-bit targets (ARM32, MIPS, RISC-V 32, etc.) where AtomicU64 is not natively available — portable-atomic provides a software fallback automatically. No extra configuration is needed. The portable-atomic dependency is included with the fallback feature enabled by default across all crates (whatsapp-rust, wacore, and whatsapp-rust-sqlite-storage).

If you’re building for a 32-bit embedded target or cross-compiling to armv7-unknown-linux-gnueabihf, whatsapp-rust will compile and run correctly out of the box.

Custom features example

If you want to use only specific features:

Cargo.toml

[dependencies]
whatsapp-rust = { version = "0.6", default-features = false, features = ["sqlite-storage", "tokio-transport"] }

Verify installation

Create a simple test file to verify the installation:

src/main.rs

use whatsapp_rust::bot::Bot;

fn main() {
    println!("whatsapp-rust installed successfully!");
}

Run it with:

cargo run

If you see “whatsapp-rust installed successfully!”, you’re ready to move on to the Quickstart guide.

Docker deployment

whatsapp-rust ships a pre-built multi-arch image to GHCR and includes a Dockerfile for building your own. The runtime image is built from scratch (only the static binary) and runs unprivileged as uid 65532.

Pre-built image

Pull from GitHub Container Registry — a single manifest resolves to linux/amd64 or linux/arm64 automatically based on the host:

docker pull ghcr.io/oxidezap/whatsapp-rust:latest

Tagged releases are also available (e.g. ghcr.io/oxidezap/whatsapp-rust:0.6.0). The image is published on every push to main, on v* tags, and can be triggered manually via the Actions tab.

Build from source

docker build -t whatsapp-rust .

The build process:

Uses rust:alpine with cargo-chef (pinned to a fixed release with --locked) for efficient, reproducible dependency caching
Detects the host target triple at build time — docker buildx build --platform linux/arm64 produces native binaries without Dockerfile changes
Enables -Zshare-generics=y (−5.6% .text) and recompiles std with the release profile (-Zbuild-std, −~300 KiB more) so it participates in fat LTO — together these two flags reduce .text by roughly 8%; the full optimization series (#842–#845) achieved 15% total
Caches dependency compilation via cargo chef cook --target in a separate layer for fast rebuilds
Produces a final image from scratch containing only the binary

Run the container

Use a named volume for /data. The container runs as uid 65532 and a named volume inherits that ownership automatically, so the SQLite database stays writable without extra setup:

docker run -v whatsapp-data:/data ghcr.io/oxidezap/whatsapp-rust:latest

For pair code authentication, pass the --phone flag:

docker run -v whatsapp-data:/data ghcr.io/oxidezap/whatsapp-rust:latest --phone 15551234567

Host bind mounts (e.g. -v ./data:/data) require the host directory to be owned by uid 65532, otherwise the container cannot write the database. Named volumes don’t have this requirement.

Upgrading from an older image

Images before this release ran as root. If an existing named volume has root-owned files, chown it once before restarting:

docker run --rm -v whatsapp-data:/data alpine chown -R 65532:65532 /data

Graceful shutdown

The container supports graceful shutdown out of the box. When the signal feature is enabled (it is by default), the bot listens for SIGTERM and Ctrl+C, disconnects cleanly from WhatsApp, and exits. Docker sends SIGTERM on docker stop, so the bot will shut down gracefully without losing session state. Since the image is built from scratch, PID 1 is the binary itself. It handles signals directly — no init system like tini is needed. This matters more than usual for PID 1: the kernel silently drops any signal a PID-1 process has no handler installed for, so an unhandled SIGTERM doesn’t just fall back to the default disposition — it’s dropped entirely, and the process only stops once docker stop’s grace period expires and it’s SIGKILLed. The bundled demo and voip-cli binaries get this via whatsapp_rust::shutdown_signal() — an exported async fn (gated on the signal feature) that resolves on the first of SIGINT or SIGTERM on Unix, or Ctrl+C elsewhere. Both handlers are armed before the future first suspends, so a signal arriving right after the first poll is still delivered. Use it in your own main() in place of a bare tokio::signal::ctrl_c() if you also deploy under Docker/Kubernetes/systemd:

tokio::select! {
    _ = &mut handle => {}
    _ = whatsapp_rust::shutdown_signal() => {
        handle.shutdown().await;
    }
}

The Dockerfile detects the host target triple at build time via rustc -vV, so docker buildx build --platform linux/arm64 (or any other supported platform) works natively without modifying the Dockerfile. The nightly-only build flags (-Zshare-generics, -Zbuild-std) apply only inside this image — stable consumers and local cargo build invocations are unaffected.

Next steps

Quickstart

Build your first WhatsApp bot in minutes

Getting Started

Core Concepts

Guides

Advanced

Prerequisites

Add to your project

Feature flags

Using stable Rust

32-bit target support

Custom features example

Verify installation

Docker deployment

Pre-built image

Build from source

Run the container

Upgrading from an older image

Graceful shutdown

Next steps

Quickstart

​Prerequisites

​Add to your project

​Feature flags

​Using stable Rust

​32-bit target support

​Custom features example

​Verify installation

​Docker deployment

​Pre-built image

​Build from source

​Run the container

​Upgrading from an older image

​Graceful shutdown

​Next steps

Quickstart

Prerequisites

Add to your project

Feature flags

Using stable Rust

32-bit target support

Custom features example

Verify installation

Docker deployment

Pre-built image

Build from source

Run the container

Upgrading from an older image

Graceful shutdown

Next steps