> ## Documentation Index
> Fetch the complete documentation index at: https://personal-9eca1d6c-claude-eager-cerf-wfbdlr.mintlify.site/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).

<Note>
  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.
</Note>

## 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
* **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

### 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

## Getting started

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/installation">
    Add whatsapp-rust to your project with cargo
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Build your first WhatsApp bot in minutes
  </Card>

  <Card title="Architecture" icon="folder-tree" href="/concepts/architecture">
    Understand the modular architecture
  </Card>

  <Card title="Custom backends" icon="database" href="/guides/custom-backends">
    Implement your own storage or transport layer
  </Card>
</CardGroup>

## Project structure

The library is organized into multiple crates for maximum flexibility:

```
whatsapp-rust/
├── src/                          # Main client library + binary
├── 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
├── transports/tokio-transport/   # Tokio WebSocket transport
├── http_clients/ureq-client/     # HTTP client for media
├── tests/e2e/                    # End-to-end test suite
└── examples/                     # Benchmark examples
```

## 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