> ## Documentation Index
> Fetch the complete documentation index at: https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](#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`:
```toml Nightly (default) theme={null}
[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"] }
```
```toml Stable Rust theme={null}
[dependencies]
whatsapp-rust = { version = "0.6", default-features = false, features = [
"sqlite-storage",
"tokio-transport",
"tokio-runtime",
"ureq-client",
"tokio-native",
"signal",
"moka-cache",
] }
whatsapp-rust-sqlite-storage = "0.6"
whatsapp-rust-tokio-transport = "0.6"
whatsapp-rust-ureq-http-client = "0.6"
wacore = { version = "0.6", default-features = false }
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](/advanced/observability) | ❌ No |
| `tracing-pii` | Render raw phone numbers in `tracing` fields instead of redacted `pn#`. Local debugging only — never enable in production | ❌ No |
| `metrics` | Emit `wa_*` counters, histograms, and gauges through the [`metrics`](https://docs.rs/metrics) facade for Prometheus/OTLP dashboards. See [Metrics](/advanced/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](/guides/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`:
```toml Cargo.toml theme={null}
[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).
```toml Cargo.toml theme={null}
[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:
```toml Cargo.toml theme={null}
[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](https://doc.rust-lang.org/cargo/reference/features.html#feature-unification) will re-enable SIMD through the `wacore` dependency:
```toml Cargo.toml theme={null}
[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`](https://crates.io/crates/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:
```toml Cargo.toml theme={null}
[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:
```rust src/main.rs theme={null}
use whatsapp_rust::bot::Bot;
fn main() {
println!("whatsapp-rust installed successfully!");
}
```
Run it with:
```bash theme={null}
cargo run
```
If you see "whatsapp-rust installed successfully!", you're ready to move on to the [Quickstart](/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
```bash theme={null}
docker build -t whatsapp-rust .
```
The build process:
1. Uses `rust:alpine` with [cargo-chef](https://github.com/LukeMathWalker/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
```bash theme={null}
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:
```bash theme={null}
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 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
Build your first WhatsApp bot in minutes