> ## Documentation Index
> Fetch the complete documentation index at: https://whatsapp-rust.jlucaso.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Introduction
> A high-performance, async Rust library for the WhatsApp Web API
# whatsapp-rust
A high-performance, async Rust library for the WhatsApp Web API. Inspired by [whatsmeow](https://github.com/tulir/whatsmeow) (Go) and [Baileys](https://github.com/WhiskeySockets/Baileys) (TypeScript).
This is an unofficial, open-source reimplementation. Using custom WhatsApp clients may violate Meta's Terms of Service and could result in account suspension. Use at your own risk.
## Key features
### Authentication
* **QR code pairing** - Scan QR code from your phone to authenticate
* **Pair code linking** - Link using phone number with 8-digit code
* **Passkey linking (SHORTCAKE\_PASSKEY)** - Gate companion linking behind a WebAuthn passkey already registered to the account
* **Persistent sessions** - Automatic reconnection with session management
### Messaging
* **End-to-end encryption** - Full Signal Protocol implementation
* **One-on-one and group chats** - Send and receive messages in any chat type
* **Message editing and reactions** - Edit sent messages and add reactions
* **Quoting/replying** - Reply to specific messages with context
* **Delivery receipts** - Track delivery, read, and played status
### Media handling
* **Upload and download** - Support for images, videos, documents, GIFs, and audio
* **Album messages** - Send grouped media albums (multiple images/videos in a single bubble)
* **Automatic encryption** - Transparent encryption/decryption for all media
### Groups and communities
* **Group management** - Create, manage, invite, membership approval, and subgroup linking
* **Community support** - Create communities, link/unlink subgroups, query participants
* **Invite links** - Generate, reset, and join via invite codes
* **Membership controls** - Approval mode, member add mode, admin promotion/demotion
### Newsletters
* **Create and join** - Create newsletters, join by JID or invite code
* **Send messages** - Plaintext messages and emoji reactions
* **Live updates** - Subscribe to real-time reaction count changes
* **Message history** - Fetch newsletter messages with pagination
### Status updates
* **Text, image, and video** - Post status updates with background colors and fonts
* **Privacy controls** - Send to all contacts, allow lists, or deny lists
* **Revocation** - Delete posted status updates
### Voice & video calls
* **Incoming and outgoing 1:1 audio and video calls** - Interoperates with the official WhatsApp app over 3G/WiFi/5G, including upgrading an audio call to video and back
* **Rust audio codec and media transport** - You own mic/camera capture and speaker/display playout. Rust handles MLow audio encoding and decoding. It also handles encryption, relay transport, and decryption for both streams. You own H.264 encoding and decoding.
* **Pure Rust MLow codec** - WhatsApp's proprietary audio codec; the `wacore` codec layer is FFI-free and compiles to WASM and embedded targets
* **Codec-neutral H.264 video** - You hand the library complete Annex-B access units; it owns RTP packetization/reassembly, PLI/FIR keyframe recovery, and encryption — no video codec dependency in `wacore` or `whatsapp-rust`
* **E2E-SRTP encryption** - Call key from the Signal session, HKDF-derived SRTP keys, AES-128-CTR + WARP integrity, for both audio and video
* **Sans-IO `CallEngine`** - No owned sockets or threads; the `wacore` engine is runtime-agnostic and compiles to WASM and embedded (esp32); the Tokio async driver is added by the top-level `voip` feature (native-only)
* **Multi-device aware** - Companion answering rekey, sibling dismiss, and offline missed-call surfacing
* **Opt-in `voip` feature** - Zero impact on default builds; codec and relay deps not compiled unless opted in
### Contacts
* **Phone number lookup** - Batch check if numbers are on WhatsApp
* **Profile pictures** - Fetch preview or full-size profile pictures
* **User info** - Get LID, status text, business status, and picture IDs
### Presence and chat state
* **Online/offline status** - Set your presence status
* **Typing indicators** - Show composing, recording, and paused states
* **Blocking** - Block and unblock contacts, query blocklist
### Chat actions
* **Archive/pin/mute** - Organize chats with archive, pin, and mute actions
* **Star messages** - Star and unstar individual messages
* **App state sync** - Actions sync across all linked devices
### Profile
* **Push name** - Set your display name with app state sync
* **Status text** - Update your "about" text
* **Profile picture** - Set or remove your profile picture
### Privacy
* **Privacy settings** - Fetch and set last seen, online, profile, status, and group add visibility
* **Disappearing messages** - Set default disappearing message duration
* **Read receipts** - Control read receipt visibility
### Architecture
* **Runtime agnostic** - Pluggable async runtime, transport, HTTP client, and storage via trait abstractions
* **Modular design** - Swap any component (Tokio, SQLite, ureq) without changing application code
* **WASM-ready** - Core protocol library (`wacore`) has zero runtime dependencies, enabling WebAssembly targets
* **SQLite included** - Default storage backend with bundled SQLite, easily swappable
* **Native plugins** - Build-time, type-safe extensions with scoped capabilities and generation-scoped lifecycle ownership behind the opt-in `plugins` feature. See [Native plugins](/advanced/plugins)
## Getting started
Add whatsapp-rust to your project with cargo
Build your first WhatsApp bot in minutes
Understand the modular architecture
Implement your own storage or transport layer
## Project structure
The library is organized into multiple crates for maximum flexibility:
```
whatsapp-rust/
├── src/ # Main client library
├── wacore/ # Platform-agnostic core (zero runtime deps)
│ ├── binary/ # WhatsApp binary protocol
│ ├── libsignal/ # Signal Protocol implementation
│ ├── appstate/ # App state management
│ ├── noise/ # Noise Protocol handshake
│ └── derive/ # Derive macros
├── waproto/ # Protocol Buffers definitions
├── storages/sqlite-storage/ # SQLite backend
├── storages/chat-store/ # Optional chat/message history store
├── transports/tokio-transport/ # Tokio WebSocket transport
├── http_clients/ureq-client/ # HTTP client for media
├── tests/e2e/ # End-to-end test suite
└── examples/ # Demo bot (demo.rs) and benchmarks
```
## Acknowledgements
This project would not be possible without the excellent work of:
* [whatsmeow](https://github.com/tulir/whatsmeow) - Go implementation
* [Baileys](https://github.com/WhiskeySockets/Baileys) - TypeScript implementation