# WhatsApp Rust

## Docs

- [Introduction](https://whatsapp-rust.jlucaso.com/introduction.md): A high-performance, async Rust library for the WhatsApp Web API
- [Installation](https://whatsapp-rust.jlucaso.com/installation.md): Add whatsapp-rust to your Rust project
- [Quickstart](https://whatsapp-rust.jlucaso.com/quickstart.md): Build your first WhatsApp bot in minutes
- [Architecture](https://whatsapp-rust.jlucaso.com/concepts/architecture.md): Understanding the whatsapp-rust project structure, modules, and workspace layout
- [Authentication](https://whatsapp-rust.jlucaso.com/concepts/authentication.md): QR code, pair code, and passkey authentication flows in whatsapp-rust
- [Events](https://whatsapp-rust.jlucaso.com/concepts/events.md): Event system, event handlers, and Event enum types in whatsapp-rust
- [Storage](https://whatsapp-rust.jlucaso.com/concepts/storage.md): Storage backends, PersistenceManager, and state management in whatsapp-rust
- [Sending Messages](https://whatsapp-rust.jlucaso.com/guides/sending-messages.md): Learn how to send text messages, reactions, channel comments, quoted replies, album messages, sticker packs, and edit messages in whatsapp-rust
- [Receiving Messages](https://whatsapp-rust.jlucaso.com/guides/receiving-messages.md): Learn how to handle incoming messages, decrypt content, and send receipts in whatsapp-rust
- [Media Handling](https://whatsapp-rust.jlucaso.com/guides/media-handling.md): Learn how to upload and download media with encryption in whatsapp-rust
- [Group Management](https://whatsapp-rust.jlucaso.com/guides/group-management.md): Learn how to create groups, manage participants, and update group metadata in whatsapp-rust
- [Newsletters (channels)](https://whatsapp-rust.jlucaso.com/guides/newsletters.md): Learn how to create, manage, and interact with WhatsApp newsletter channels in whatsapp-rust
- [Community management](https://whatsapp-rust.jlucaso.com/guides/communities.md): Learn how to create communities, manage subgroups, query community metadata, send encrypted CAG reactions, and post channel comments in whatsapp-rust
- [Polls](https://whatsapp-rust.jlucaso.com/guides/polls.md): Learn how to create polls, cast votes, and decrypt poll results in whatsapp-rust
- [VoIP Calls](https://whatsapp-rust.jlucaso.com/guides/voip-calls.md): Place and answer end-to-end encrypted 1:1 voice and video calls with whatsapp-rust
- [Custom Backends](https://whatsapp-rust.jlucaso.com/guides/custom-backends.md): Learn how to implement custom storage, transport, and HTTP backends for whatsapp-rust
- [Signal Protocol Implementation](https://whatsapp-rust.jlucaso.com/advanced/signal-protocol.md): Deep dive into end-to-end encryption, Double Ratchet algorithm, and Signal Protocol in whatsapp-rust
- [WhatsApp Binary Protocol](https://whatsapp-rust.jlucaso.com/advanced/binary-protocol.md): Deep dive into WhatsApp's custom binary serialization format, node marshaling, and protocol specifics
- [State Management & Persistence](https://whatsapp-rust.jlucaso.com/advanced/state-management.md): Device state management, PersistenceManager, and the DeviceCommand pattern in whatsapp-rust
- [WebSocket & Noise Protocol](https://whatsapp-rust.jlucaso.com/advanced/websocket-handling.md): NoiseSocket, connection management, handshake protocol, and frame handling in whatsapp-rust
- [Observability with tracing](https://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/advanced/metrics.md): Emit Prometheus and OTLP-ready wa_* counters, histograms, and gauges from whatsapp-rust with the opt-in metrics feature.
- [Inbound Durability Hook](https://whatsapp-rust.jlucaso.com/advanced/inbound-durability.md): Opt in to at-least-once message delivery by deferring the transport ack until your consumer durably commits each batch of messages.
- [Retry Admission Hook](https://whatsapp-rust.jlucaso.com/advanced/retry-admission.md): Opt in to bounding a storm of inbound group/status retry receipts, without changing the SDK's default WhatsApp Web-compliant behavior.
- [Native plugins](https://whatsapp-rust.jlucaso.com/advanced/plugins.md): Build type-safe, capability-scoped extensions for whatsapp-rust behind the opt-in plugins feature, with build-time registration and generation-scoped lifecycle ownership.
- [Codegen flags for performance](https://whatsapp-rust.jlucaso.com/advanced/build-flags.md): Optional target-feature flags you can set for roughly a fifth fewer instructions on the Signal encrypt paths — and why whatsapp-rust does not set them for you.
- [Client](https://whatsapp-rust.jlucaso.com/api/client.md): Core client for WhatsApp connectivity and protocol operations
- [Bot](https://whatsapp-rust.jlucaso.com/api/bot.md): High-level builder for creating WhatsApp bots with event handlers
- [Error Types](https://whatsapp-rust.jlucaso.com/api/errors.md): Typed error reference for all whatsapp-rust public APIs
- [send](https://whatsapp-rust.jlucaso.com/api/send.md): Send, forward, edit, revoke, pin, and unpin messages with advanced options, including album support
- [download](https://whatsapp-rust.jlucaso.com/api/download.md): Download and decrypt media from WhatsApp messages
- [upload](https://whatsapp-rust.jlucaso.com/api/upload.md): Upload and encrypt media for sending in messages
- [Media reupload](https://whatsapp-rust.jlucaso.com/api/media-reupload.md): Request re-upload of media with expired CDN URLs
- [receipt](https://whatsapp-rust.jlucaso.com/api/receipt.md): Send read receipts, delivery receipts, and played receipts
- [Groups](https://whatsapp-rust.jlucaso.com/api/groups.md): Group management operations - create, modify, and manage WhatsApp groups
- [Contacts](https://whatsapp-rust.jlucaso.com/api/contacts.md): Contact lookup, profile picture, and user info operations
- [Presence](https://whatsapp-rust.jlucaso.com/api/presence.md): Online/offline status and presence subscription operations
- [Chatstate](https://whatsapp-rust.jlucaso.com/api/chatstate.md): Typing indicators and chat state notifications
- [Blocking](https://whatsapp-rust.jlucaso.com/api/blocking.md): Block and unblock contacts, manage blocklist
- [Bots](https://whatsapp-rust.jlucaso.com/api/bots.md): Fetch WhatsApp's directory of first-party AI bots
- [Status](https://whatsapp-rust.jlucaso.com/api/status.md): Post, react to, and manage WhatsApp status/story updates
- [Profile](https://whatsapp-rust.jlucaso.com/api/profile.md): Manage your own profile - push name, status text, and profile picture
- [Chat actions](https://whatsapp-rust.jlucaso.com/api/chat-actions.md): Archive, pin, mute, delete chats, star messages, and mark chats as read
- [Labels](https://whatsapp-rust.jlucaso.com/api/labels.md): Create, delete, and associate WhatsApp chat labels, and react to label changes from linked devices
- [Quick Replies](https://whatsapp-rust.jlucaso.com/api/quick-replies.md): Create, edit, and delete WhatsApp Business quick replies, and react to changes from linked devices
- [Privacy](https://whatsapp-rust.jlucaso.com/api/privacy.md): Privacy settings management - fetch, update, and configure account privacy
- [Business](https://whatsapp-rust.jlucaso.com/api/business.md): Business profile operations, catalog and collection browsing, order lookup, and business profile/cover photo management
- [MEX (GraphQL)](https://whatsapp-rust.jlucaso.com/api/mex.md): Execute typed GraphQL queries and mutations via Meta Exchange persisted operations
- [Newsletter](https://whatsapp-rust.jlucaso.com/api/newsletter.md): Newsletter (channel) operations — create, manage, administer, subscribe, and send messages to WhatsApp channels
- [Community](https://whatsapp-rust.jlucaso.com/api/community.md): Community operations — create, deactivate, and manage community subgroups
- [Polls](https://whatsapp-rust.jlucaso.com/api/polls.md): Poll creation, voting, and vote decryption API reference
- [Events](https://whatsapp-rust.jlucaso.com/api/events.md): Create WhatsApp event messages and collect encrypted RSVPs
- [Spam reporting](https://whatsapp-rust.jlucaso.com/api/spam-report.md): Report messages and contacts as spam to WhatsApp
- [TC Token](https://whatsapp-rust.jlucaso.com/api/tctoken.md): Manage trusted contact privacy tokens and cstoken fallback
- [Signal](https://whatsapp-rust.jlucaso.com/api/signal.md): Low-level Signal protocol operations for encryption, decryption, and session management
- [USync](https://whatsapp-rust.jlucaso.com/api/usync.md): Typed USync query engine for user sync, device lists, profiles, and bot metadata
- [Storage Traits](https://whatsapp-rust.jlucaso.com/api/store.md): Storage backend traits and SQLite implementation for persistent state
- [Chat Store](https://whatsapp-rust.jlucaso.com/api/chat-store.md): Optional SQLite-backed chat and message history store
- [Transport Trait](https://whatsapp-rust.jlucaso.com/api/transport.md): Network transport abstraction and WebSocket implementation
- [HTTP Client Trait](https://whatsapp-rust.jlucaso.com/api/http-client.md): HTTP client abstraction and ureq implementation for media operations
- [wacore](https://whatsapp-rust.jlucaso.com/api/wacore.md): Platform-agnostic WhatsApp protocol implementation
- [waproto](https://whatsapp-rust.jlucaso.com/api/waproto.md): Protocol Buffers definitions for WhatsApp messages
- [Changelog](https://whatsapp-rust.jlucaso.com/changelog/overview.md): Product updates and improvements to whatsapp-rust
- [August 7, 2026 — whatsapp-rust 0.7.0 published](https://whatsapp-rust.jlucaso.com/changelog/2026-08-07-release-0-7-0.md): 0.7.0 is on crates.io. VoIP, native plugins, tracing, and metrics no longer need a git dependency; the moka-cache and debug-diagnostics features are gone.
- [June 15, 2026 — Binary encode: length-bucketed token lookup](https://whatsapp-rust.jlucaso.com/changelog/2026-06-15-token-tiny-map.md): index_of_token switches from a PTHash perfect-hash map to hashify::tiny_map!, cutting marshal_auto_small latency by 34% on the miss-heavy uncached encode path.
- [June 14, 2026 — Drop moka: PortableCache is now the sole in-process cache backend](https://whatsapp-rust.jlucaso.com/changelog/2026-06-14-drop-moka-portable-cache.md): Removes the moka dependency (-2.55 MiB stripped, -21% .text). PortableCache gains monotonic TTL/TTI, eager init-lock reclamation, and a reliable async clear(). TypedCache::from_moka is renamed to from_local.
- [June 12, 2026 — Binary size CI: per-PR budget gate and historical tracking](https://whatsapp-rust.jlucaso.com/changelog/2026-06-12-binary-size-ci.md): Every PR now runs a release build and checks stripped size and .text growth against an absolute budget. A Chart.js series on gh-pages tracks every main merge over time.
- [June 11, 2026 — Bot API overhaul (breaking)](https://whatsapp-rust.jlucaso.com/changelog/2026-06-11-bot-api-overhaul.md): Lifecycle simplification, typed event registrars, single-dependency consumption, and messaging sugar ahead of 1.0.
- [June 11, 2026 — Docker image: share-generics, build-std, multi-arch](https://whatsapp-rust.jlucaso.com/changelog/2026-06-11-dockerfile-share-generics.md): Reduces the release binary .text section by ~15% cumulatively through -Zshare-generics=y and -Zbuild-std, and enables native multi-arch docker buildx builds.
- [June 11, 2026 — PDO placeholder-resend: at-most-once per message](https://whatsapp-rust.jlucaso.com/changelog/2026-06-11-pdo-once-per-message.md): Adds a pdo_requested memo cache that caps PDO placeholder-resend requests to one per message, skips a redundant migration retry decrypt when nothing moved, and adjusts noisy log levels.
- [June 11, 2026 — History sync: secret-presence pre-scan, Arc chat ids, schema-pinned wire tags](https://whatsapp-rust.jlucaso.com/changelog/2026-06-11-history-sync-secret-prescan.md): History sync skips prost decode for secret-free messages, shares conversation ids via Arc<str>, and replaces magic wire-tag numbers with generated schema-pinned consts. HistoryMsgSecretRecord field types changed.
- [June 10, 2026 — impl Into<Jid> API convention](https://whatsapp-rust.jlucaso.com/changelog/2026-06-10-jid-into-api-convention.md): All mutating public methods now accept impl Into<Jid>. Pass &jid directly without cloning; existing owned-Jid call sites continue to compile unchanged.
- [June 10, 2026 — Prekey upload window reuse (WA Web parity)](https://whatsapp-rust.jlucaso.com/changelog/2026-06-10-prekey-unupload-watermark.md): The prekey upload path now tracks a first-unuploaded watermark alongside the generation counter, matching WA Web's two-watermark model. Batches re-offer leftover generated-but-unuploaded keys before minting new ones, and retry-receipt keys are reused from the window head. Custom backend implementati…
- [June 10, 2026 — Encrypted CAG reactions and channel comments](https://whatsapp-rust.jlucaso.com/changelog/2026-06-10-cag-enc-reactions-comments.md): Reactions to Community Announcement Group posts are now encrypted automatically. A new comments() API lets you send and receive encrypted threaded replies on CAG channel posts.
- [June 10, 2026 — Contacts: fix async_trait / boxed-future compilation error](https://whatsapp-rust.jlucaso.com/changelog/2026-06-10-hrtb-closures.md): is_on_whatsapp() and get_user_info() now compile correctly when called from #[async_trait] implementations or any context that boxes the returned future.
- [June 10, 2026 — Group send: server-aware LID-PN probe on warm device lookups](https://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/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://whatsapp-rust.jlucaso.com/changelog/2026-06-02.md): Bot message decryption, streaming uploads, typed event subscriptions, and WhatsApp Web parity improvements