# WhatsApp Rust

## Docs

- [Introduction](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/introduction.md): A high-performance, async Rust library for the WhatsApp Web API
- [Installation](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/installation.md): Add whatsapp-rust to your Rust project
- [Quickstart](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/quickstart.md): Build your first WhatsApp bot in minutes
- [Architecture](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/concepts/architecture.md): Understanding the whatsapp-rust project structure, modules, and workspace layout
- [Authentication](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/concepts/authentication.md): QR code and pair code authentication flows in whatsapp-rust
- [Events](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/concepts/events.md): Event system, event handlers, and Event enum types in whatsapp-rust
- [Storage](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/concepts/storage.md): Storage backends, PersistenceManager, and state management in whatsapp-rust
- [Sending Messages](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/guides/sending-messages.md): Learn how to send text messages, reactions, quoted replies, album messages, sticker packs, and edit messages in whatsapp-rust
- [Receiving Messages](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/guides/receiving-messages.md): Learn how to handle incoming messages, decrypt content, and send receipts in whatsapp-rust
- [Media Handling](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/guides/media-handling.md): Learn how to upload and download media with encryption in whatsapp-rust
- [Group Management](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/guides/group-management.md): Learn how to create groups, manage participants, and update group metadata in whatsapp-rust
- [Newsletters (channels)](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/guides/newsletters.md): Learn how to create, manage, and interact with WhatsApp newsletter channels in whatsapp-rust
- [Community management](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/guides/communities.md): Learn how to create communities, manage subgroups, and query community metadata in whatsapp-rust
- [Polls](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/guides/polls.md): Learn how to create polls, cast votes, and decrypt poll results in whatsapp-rust
- [Custom Backends](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/guides/custom-backends.md): Learn how to implement custom storage, transport, and HTTP backends for whatsapp-rust
- [Signal Protocol Implementation](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/advanced/signal-protocol.md): Deep dive into end-to-end encryption, Double Ratchet algorithm, and Signal Protocol in whatsapp-rust
- [WhatsApp Binary Protocol](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/advanced/binary-protocol.md): Deep dive into WhatsApp's custom binary serialization format, node marshaling, and protocol specifics
- [State Management & Persistence](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/advanced/state-management.md): Device state management, PersistenceManager, and the DeviceCommand pattern in whatsapp-rust
- [WebSocket & Noise Protocol](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/advanced/websocket-handling.md): NoiseSocket, connection management, handshake protocol, and frame handling in whatsapp-rust
- [Observability with tracing](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/advanced/observability.md): Wire whatsapp-rust into tracing-subscriber or OpenTelemetry with the optional tracing feature, redacted JIDs, and a wa.* span taxonomy.
- [Metrics with the metrics facade](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/advanced/metrics.md): Emit Prometheus and OTLP-ready wa_* counters, histograms, and gauges from whatsapp-rust with the opt-in metrics feature.
- [Client](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/client.md): Core client for WhatsApp connectivity and protocol operations
- [Bot](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/bot.md): High-level builder for creating WhatsApp bots with event handlers
- [send](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/send.md): Send, forward, edit, revoke, pin, and unpin messages with advanced options, including album support
- [download](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/download.md): Download and decrypt media from WhatsApp messages
- [upload](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/upload.md): Upload and encrypt media for sending in messages
- [Media reupload](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/media-reupload.md): Request re-upload of media with expired CDN URLs
- [receipt](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/receipt.md): Send read receipts, delivery receipts, and played receipts
- [Groups](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/groups.md): Group management operations - create, modify, and manage WhatsApp groups
- [Contacts](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/contacts.md): Contact lookup, profile picture, and user info operations
- [Presence](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/presence.md): Online/offline status and presence subscription operations
- [Chatstate](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/chatstate.md): Typing indicators and chat state notifications
- [Blocking](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/blocking.md): Block and unblock contacts, manage blocklist
- [Status](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/status.md): Post, react to, and manage WhatsApp status/story updates
- [Profile](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/profile.md): Manage your own profile - push name, status text, and profile picture
- [Chat actions](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/chat-actions.md): Archive, pin, mute, delete chats, star messages, and mark chats as read
- [Labels](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/labels.md): Create, delete, and associate WhatsApp chat labels, and react to label changes from linked devices
- [Privacy](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/privacy.md): Privacy settings management - fetch, update, and configure account privacy
- [Business](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/business.md): Business profile operations - fetch WhatsApp Business account profiles and handle business events
- [MEX (GraphQL)](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/mex.md): Execute typed GraphQL queries and mutations via Meta Exchange persisted operations
- [Newsletter](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/newsletter.md): Newsletter (channel) operations — create, manage, subscribe, and send messages to WhatsApp channels
- [Community](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/community.md): Community operations — create, deactivate, and manage community subgroups
- [Polls](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/polls.md): Poll creation, voting, and vote decryption API reference
- [Events](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/events.md): Create WhatsApp event messages and collect encrypted RSVPs
- [Spam reporting](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/spam-report.md): Report messages and contacts as spam to WhatsApp
- [TC Token](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/tctoken.md): Manage trusted contact privacy tokens and cstoken fallback
- [Signal](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/signal.md): Low-level Signal protocol operations for encryption, decryption, and session management
- [Storage Traits](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/store.md): Storage backend traits and SQLite implementation for persistent state
- [Transport Trait](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/transport.md): Network transport abstraction and WebSocket implementation
- [HTTP Client Trait](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/http-client.md): HTTP client abstraction and ureq implementation for media operations
- [wacore](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/wacore.md): Platform-agnostic WhatsApp protocol implementation
- [waproto](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/api/waproto.md): Protocol Buffers definitions for WhatsApp messages
- [Changelog](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/overview.md): Product updates and improvements to whatsapp-rust
- [June 10, 2026 — Group send: per-group device list memoized behind a topology generation](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-10-group-devices-memo.md): Warm repeat sends to the same group skip the per-member registry fan-out entirely. A topology generation counter fused into every device-registry and LID-PN write ensures the memo is invalidated by construction.
- [June 10, 2026 — Group send: server-aware LID-PN probe on warm device lookups](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-10-server-aware-lookup-probe.md): get_devices_from_registry now probes only the single relevant direction of the LID-PN cache per member, cutting device resolution from 3 cache operations to 2 and reducing warm 800-member send latency by 26%.
- [June 10, 2026 — Group send: participant-list hash via single arena](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-10-phash-arena-sort.md): participant_list_hash now formats all device JIDs into one shared string buffer and sorts lightweight range views, cutting per-call heap allocations from O(n) to 3 for an 800-device group.
- [June 10, 2026 — Binary: inline attribute storage via SmallVec](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-10-attrs-inline-smallvec.md): Attrs now stores up to 2 attributes inline, cutting per-node heap allocations on the encode path. IqError::Disconnected now wraps Box<Node>.
- [June 9, 2026 — Protocol error-handling strictness](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-09-error-strictness.md): Several protocol paths that previously swallowed errors or returned ambiguous results now signal failures explicitly. is_on_whatsapp rejects unsupported JID types, per-subprotocol errors are preserved on IsOnWhatsAppResult and UserInfo, device-list/LID batch queries degrade per user, and IQ response…
- [June 9, 2026 — Device snapshot cached as Arc<Device>](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-09-arc-device-snapshot.md): get_device_snapshot() is now sync and returns Arc<Device>. The related client accessors (get_pn, get_lid, get_push_name, generate_message_id) are also sync. Breaking change: drop .await at all call sites.
- [June 9, 2026 — Zero-copy inbound frame feeding](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-09-recv-zero-copy.md): FrameDecoder gains feed_bytes, eliminating the last full memcpy on the receive path in steady state.
- [June 9, 2026 — Events & RSVP, quiz polls, disappearing timers, and media builders](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-09.md): Create events and collect RSVPs, send quiz polls, toggle 1:1 disappearing timers, save contacts, clear chats, mute channels, and build media messages from an upload result — plus breaking changes to download, groups, and receipt APIs.
- [June 9, 2026 — Response structs marked #[non_exhaustive]](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-09-non-exhaustive.md): All library-returned response and result structs are now #[non_exhaustive], completing the pre-1.0 API stabilisation pass.
- [June 9, 2026 — Device list: primary device preserved on identity rotation](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-09-device-list.md): Fixed a bug where a companion relink or identity rotation could silently drop device 0 from the stored device list, preventing encrypted messages from reaching the primary phone.
- [June 9, 2026 — Device list: primary device preserved on device-remove](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-09-device-list-remove.md): Fixed a bug where a remove notification targeting device 0 could silently drop the primary from the stored device list, suppressing the usync re-fetch and causing encrypted messages to miss the primary phone.
- [June 9, 2026 — Device registry: empty record treated as a cache miss](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-09-usync-empty-record.md): Fixed a bug where a present-but-empty device record was returned as authoritative, permanently blocking encrypted sends to the affected user. The registry now treats an empty record as a miss so it self-heals from the network.
- [June 9, 2026 — Retry: device-list resync on unknown-device retry](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-09-retry-resync.md): Fixed an infinite retry loop where a newly-linked device absent from the local registry would retry group messages forever because it was never included in subsequent sends. Retries from unknown devices now trigger a device-list resync, learning the device for the next send.
- [June 9, 2026 — Signal session cache: Arc-shared records, zero-copy peek](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-09-arc-session-cache.md): peek_session now returns Arc<SessionRecord> — cache hits are a refcount bump instead of a 1–2 KB deep clone. Breaking: return type changes from Option<SessionRecord> to Option<Arc<SessionRecord>>.
- [June 9, 2026 — LidPnEntry: Arc<str> fields for unbounded-cache memory savings](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-09-lid-pn-arc-str.md): LidPnEntry.lid and .phone_number are now Arc<str>. Cache keys share the entry's Arc allocations, halving per-mapping heap objects in the unbounded LID-PN cache.
- [June 9, 2026 — Group send: session setup hoisted out of chain lock](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-09-group-send-perf.md): Concurrent sends to the same group no longer serialize behind prekey fetch I/O. The sender-key chain lock now covers only the CPU-bound SKDM creation and skmsg encrypt. A new per-group session-setup lock serializes cold prekey fetch and X3DH without blocking warm sends.
- [June 9, 2026 — GroupInfo: derived PN→LID index, smaller cache and disk footprint](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-09-groupinfo-lid-pn-maps.md): The pn_to_lid_map reverse index is now derived and skipped during serialization, roughly halving LID-group mapping bytes in memory and on disk. Breaking: lid_jid_for_phone_user is renamed to lid_user_for_phone_user and returns Option<&CompactString> instead of Option<&Jid>.
- [June 9, 2026 — App state sync: move-not-clone through blocking handoff](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-09-appstate-blocking-handoff.md): process_patch_list no longer deep-clones the SyncdSnapshot or each SyncdPatch to satisfy the 'static bound on spawn_blocking. The data moves into each closure and comes back via the return tuple, eliminating multi-MB copies on bootstrap and resume.
- [June 8, 2026 — Forward messages, played receipts, and group pictures](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-08.md): Forward messages with a new high-level API, send played receipts for voice/video notes, and manage group profile pictures.
- [June 6, 2026 — Optional tracing instrumentation](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-06.md): Opt-in tracing feature instruments connect, send, receive, IQ, app state, pairing, media, and session flows with a wa.* span taxonomy and PII-redacted JIDs.
- [June 5, 2026 — Typed A/B-props registry](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-05-abprops.md): Vendored, auto-generated A/B-props registry replaces hand-maintained config codes; AbPropsCache now takes typed AbProp constants.
- [June 5, 2026](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-05.md): Typed MEX operations, reaction helpers, newsletter edit/revoke, and an E2E send-path guard for newsletter JIDs.
- [June 4, 2026](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-04.md): New Labels API, a generic send_app_state_action escape hatch for syncd actions, query_info now returns Arc<GroupInfo>, and a wire-shape fix for message edits.
- [Week of June 2, 2026](https://personal-9eca1d6c-claude-eager-cerf-0xyrbp.mintlify.site/changelog/2026-06-02.md): Bot message decryption, streaming uploads, typed event subscriptions, and WhatsApp Web parity improvements