Installation

Add whatsapp-rust to your Rust project

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

Add whatsapp-rust and its required dependencies to your Cargo.toml:

Nightly (default)

[dependencies]
whatsapp-rust = "0.6"
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"] }

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
generate	Enables prost-build for regenerating protobuf code from whatsapp.proto. Only needed when modifying the .proto file	❌ No
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

The generated protobuf code (whatsapp.rs) is checked into version control, so prost-build is never needed for normal builds. This keeps the dependency tree smaller and compilation faster. 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:

1. Uses rust:alpine with cargo-chef for efficient dependency caching
2. Compiles natively against musl on Alpine for a fully static binary
3. Caches dependency compilation via cargo chef cook in a separate layer for fast rebuilds
4. 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 [phone]

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 uses rust:alpine which builds for the host architecture’s musl target. For cross-compilation to other architectures, you need to modify the base image and build configuration in the Dockerfile.

Next steps

Quickstart

Build your first WhatsApp bot in minutes