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

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",
    "moka-cache",
] }
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
`moka-cache`	Moka in-memory cache	✅ 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
`danger-skip-tls-verify`	Skip TLS verification (unsafe)	❌ No
`debug-snapshots`	Debug protocol snapshots	❌ No
`debug-diagnostics`	Memory diagnostics API (`MemoryDiagnostics`)	❌ 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

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 (prost generates PascalCase 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 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",
    "moka-cache",
] }
# 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 includes a Dockerfile for building a minimal, statically linked container image. The multi-stage build produces a scratch-based image with only the compiled binary.

Build the image

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

docker run -v ./data:/data whatsapp-rust

The container uses /data as its working directory, so mount a volume there to persist your SQLite database and session data across restarts. For pair code authentication, pass the --phone flag:

docker run -v ./data:/data whatsapp-rust --phone 15551234567

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.

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

Build the image

Run the container

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

​Build the image

​Run the container

​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

Build the image

Run the container

Graceful shutdown

Next steps