Events - WhatsApp Rust

Overview

WhatsApp-Rust uses an event-driven architecture where the client emits events for all WhatsApp protocol interactions. Your application subscribes to these events to handle messages, connection changes, and notifications.

Event system architecture

CoreEventBus

Location: wacore/src/types/events.rs

#[derive(Default, Clone)]
pub struct CoreEventBus {
    handlers: Arc<RwLock<Vec<Arc<dyn EventHandler>>>>,
}

impl CoreEventBus {
    pub fn dispatch(&self, event: Event) {
        let handlers = self.handlers.read().expect("...").clone();
        if handlers.is_empty() {
            return;
        }
        let event = Arc::new(event);
        for handler in &handlers {
            handler.handle_event(Arc::clone(&event));
        }
    }

    pub fn has_handlers(&self) -> bool {
        !self.handlers.read().expect("...").is_empty()
    }
}

Features:

Thread-safe event dispatching via Arc<Event> — each event is wrapped once and shared across all handlers, eliminating deep clones
Multiple handlers supported
Clone-cheap with Arc

EventHandler Trait

pub trait EventHandler: Send + Sync {
    fn handle_event(&self, event: Arc<Event>);

    /// Which event kinds this handler wants. Defaults to all kinds.
    /// Override to let the bus skip materializing events you don't want.
    fn interest(&self) -> EventInterest {
        EventInterest::ALL
    }
}

Handlers receive Arc<Event> — a shared reference-counted pointer to the event. Since Arc<Event> implements Deref<Target = Event>, you can pattern-match on it directly. Implementation:

use wacore::types::events::{Event, InboundMessage};
use std::sync::Arc;

struct MyHandler;

impl EventHandler for MyHandler {
    fn handle_event(&self, event: Arc<Event>) {
        match &*event {
            Event::Messages(batch) => {
                for InboundMessage { message: msg, info, .. } in batch.iter() {
                    println!("Message from {}: {:?}", info.source.sender, msg);
                }
            }
            _ => {}
        }
    }
}

client.register_handler(Arc::new(MyHandler));

Typed event interest (skip boxing unwanted events)

By default a handler receives every event. If you only care about a few kinds, override interest() so the event bus skips building and dispatching the kinds nobody wants — for high-throughput events (presence, receipts) this avoids the per-event Arc allocation entirely.

use wacore::types::events::{EventInterest, EventKind};

impl EventHandler for MyHandler {
    fn handle_event(&self, event: Arc<Event>) { /* … */ }

    fn interest(&self) -> EventInterest {
        // Only Messages and Connected events reach this handler.
        EventInterest::of(&[EventKind::Messages, EventKind::Connected])
    }
}

EventKind is a #[repr(u8)] discriminant — one variant per Event variant (Messages, Connected, Receipt, …). The enum is #[non_exhaustive], so match blocks on EventKind must include a wildcard arm (_ => …); new kinds may be added in minor releases as the library tracks new server events.
EventKind::CAPACITY is a public u8 constant (currently 128) that bounds the number of kinds. It exists because each discriminant is packed as a bit in EventInterest’s u128 mask, and a future variant that would overflow it fails compilation rather than silently corrupting the mask at runtime. Treat it as a read-only ceiling — you don’t need to check it at runtime.
EventInterest is a 128-bit set of kinds. Build it with EventInterest::of(&[…]), EventInterest::ALL (the default), EventInterest::none(), or chain .with(kind). Query it with .wants(kind).
The bus exposes has_handler_for(kind) and only produces an event when at least one registered handler wants its kind.

EventInterest was widened from a u64 to a u128 mask (and EventKind::CAPACITY from 64 to 128) as part of the pre-1.0 event-payload API freeze, since the kind count had reached 58/64. The public surface (EventInterest::of, .with(kind), .wants(kind), EventInterest::ALL) is unchanged — only the internal bit width doubled, giving headroom for future event kinds.

With the Bot builder, the same narrowing is available via on_event_for:

bot.on_event_for(&[EventKind::Messages], |event, client| async move {
    // only Messages events
});

on_event (without kinds) keeps subscribing to everything.

Event Enum

Location: wacore/src/types/events.rs

#[derive(Debug, Clone, Serialize)]
#[non_exhaustive]
pub enum Event {
    // Connection
    Connected(Connected),
    Disconnected(Disconnected),
    StreamReplaced(StreamReplaced),
    StreamError(StreamError),
    ConnectFailure(ConnectFailure),
    TemporaryBan(TemporaryBan),

    // Pairing
    PairingQrCode(PairingQrCode),
    PairingCode(PairingCode),
    PairingCodeRefresh(PairingCodeRefresh),
    PairingCodeError(PairingCodeError),
    PairingQrCodesExhausted(PairingQrCodesExhausted),
    PairSuccess(PairSuccess),
    PairError(PairError),
    QrScannedWithoutMultidevice(QrScannedWithoutMultidevice),
    ClientOutdated(ClientOutdated),
    LoggedOut(LoggedOut),

    // Messages
    Messages(MessageBatch),
    Receipt(Receipt),
    UndecryptableMessage(UndecryptableMessage),
    Notification(Arc<OwnedNodeRef>),
    ServerAck(ServerAck),

    // Presence
    ChatPresence(ChatPresenceUpdate),
    Presence(PresenceUpdate),

    // User Updates
    PictureUpdate(PictureUpdate),
    UserAboutUpdate(UserAboutUpdate),
    RetiredPushNameUpdate(RetiredPushNameUpdate),
    SelfPushNameUpdated(SelfPushNameUpdated),

    // Group Updates
    GroupUpdate(GroupUpdate),

    // Contact Updates
    ContactUpdated(ContactUpdated),
    ContactNumberChanged(ContactNumberChanged),
    ContactSyncRequested(ContactSyncRequested),
    ContactUpdate(ContactUpdate),
    ContactRemoved(ContactRemoved),

    // Chat State
    PinUpdate(PinUpdate),
    MuteUpdate(MuteUpdate),
    ArchiveUpdate(ArchiveUpdate),
    StarUpdate(StarUpdate),
    MarkChatAsReadUpdate(MarkChatAsReadUpdate),
    DeleteChatUpdate(DeleteChatUpdate),
    ClearChatUpdate(ClearChatUpdate),
    UserStatusMuteUpdate(UserStatusMuteUpdate),
    DeleteMessageForMeUpdate(DeleteMessageForMeUpdate),
    LabelEditUpdate(LabelEditUpdate),
    LabelAssociationUpdate(LabelAssociationUpdate),
    MessageLabelAssociationUpdate(MessageLabelAssociationUpdate),
    QuickReplyUpdate(QuickReplyUpdate),

    // History Sync
    HistorySync(Box<LazyHistorySync>),
    OfflineSyncPreview(OfflineSyncPreview),
    OfflineSyncCompleted(OfflineSyncCompleted),
    OfflineSyncInterrupted(OfflineSyncInterrupted),
    DirtyState(DirtyState),
    AppStateSyncFailed(AppStateSyncFailed),
    ClientExpirationChanged(ClientExpirationChanged),

    // Device Updates
    DeviceListUpdate(DeviceListUpdate),
    IdentityChange(IdentityChange),
    BusinessStatusUpdate(BusinessStatusUpdate),

    // Newsletter
    NewsletterLiveUpdate(NewsletterLiveUpdate),

    // Calls
    IncomingCall(Box<IncomingCall>),

    // Notification Updates
    DisappearingModeChanged(DisappearingModeChanged),

    // Privacy
    DisableLinkPreviewsUpdate(DisableLinkPreviewsUpdate),

    // Raw stanza (opt-in)
    RawNode(Arc<OwnedNodeRef>),

    // Passkey linking (SHORTCAKE_PASSKEY)
    PairPasskeyRequest(PairPasskeyRequest),
    PairPasskeyConfirmation(PairPasskeyConfirmation),
    PairPasskeyError(PairPasskeyError),

    // Decrypted payload (opt-in)
    DecryptedPayload(DecryptedPayload),

    // Sent frame (opt-in)
    SentFrame(SentFrame),

    // Enc decrypt failure (opt-in)
    EncDecryptFailed(EncDecryptFailed),
}

The Event enum is #[non_exhaustive], so your match statements must include a wildcard arm (_ => {}). New variants may be added in minor releases without a breaking change.

Payload stability: every event payload struct is sealed with #[non_exhaustive] plus a bon builder for construction (Type::builder()…build()), so a payload can gain fields later without breaking consumers. The freeze rolled out in stages. ServerAck went first, then the notification/presence/contact/group payloads and the app-state-sync mutation payloads, then the remaining message/newsletter/device/pairing payloads and three more unit-marker events. At the time, each of those three was an empty sealed struct built as Connected::builder().build(): Connected, QrScannedWithoutMultidevice, StreamReplaced. The rollout is now complete across the whole Event surface. Two unit-marker events have since gained a field and stopped being empty: ClientOutdated gained raw (see ClientOutdated below), and Connected gained app_version_fallback in PR #1360 (see Connected below). QrScannedWithoutMultidevice and StreamReplaced are the two still empty today. Read the fields you need (e.g. ack.class) or keep a .. rest when destructuring (required for a #[non_exhaustive] struct pattern from outside the defining crate — e.g. InboundMessage { message, info, .. }), rather than binding every field. A maybe-absent field is always modeled as Option<T> (with a maybe_* builder setter), never an empty-string or zero sentinel. The library itself constructs every payload via its builder — a struct literal from outside wacore/whatsapp-rust no longer compiles (E0639).

Connection Events

Connected

Emitted: After the session is authenticated and has asked the server to leave passive mode. On a fresh pairing (and on any reconnect before the account’s critical app-state collections have synced), the client waits for the critical app-state sync to produce an answer first — see Critical app-state sync (pairing bootstrap) — so the push name and blocklist are normally in place by the time this fires. As of PR #1291, it waits but does not withhold: a critical collection the server refused or couldn’t deliver is reported via AppStateSyncFailed and Connected fires regardless, since a session already delivering messages shouldn’t leave a consumer believing nothing ever connected.

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct Connected {
    pub app_version_fallback: Option<AppVersionFallback>,
}

Event::Connected(Connected::builder().build())

Fields:

app_version_fallback — added in PR #1360; additive, so an existing Connected::builder().build() still compiles (app_version_fallback defaults to None). Present when this connect could not resolve the app version from its source and settled for the version the device already held instead. Absent on every normal connect, so Some is the whole signal. In practice this only fires on the wasm32 target. The native build’s source is web.whatsapp.com/sw.js. A client that can’t reach it treats that as a real break of WhatsApp Web itself, and fails connect() with ConnectError::Version instead of falling back — see ConnectError. The browser build’s source is the Facebook JS SDK bundle at connect.facebook.net, which sits on common tracker blocklists (uBlock Origin, Brave shields, corporate DNS). A client blocked from reaching it connects anyway, on the version it already has, rather than refusing to connect over what is, for a large share of browser users, an ad blocker doing its job.

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct AppVersionFallback {
    pub version: (u32, u32, u32),
    pub compiled_default: bool,
    pub reason: AppVersionFallbackReason,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[non_exhaustive]
pub enum AppVersionFallbackReason {
    /// The source refused the request or never answered — e.g. a blocked domain.
    SourceUnreachable,
    /// The source answered, but the version was no longer where it should be.
    SourceUnparsable,
}

AppVersionFallback::version — the version this session actually connected with.
AppVersionFallback::compiled_default — true when that version is the one compiled into the library. The payload carries no resolution timestamp for it, so treat the release’s age as a lower bound on its staleness, not the exact figure — the bundled revision could already have been behind current WhatsApp Web when this release was cut. false when the device had already resolved a version on an earlier connect, so its staleness is only however long it’s been since that version was last successfully resolved — that’s the length of this outage only if the previous connect is what resolved it; a longer-running outage across several connects makes it older still. (A with_version call on this connect never produces a fallback at all — see the with_version note — but a device that carried an override from a past connect and later drops it can still hit this path, and would correctly report false here too.)
AppVersionFallback::reason — SourceUnreachable is the routine case: a blocked or offline source. It often clears on a later connect once the block or outage lifts, though a durable blocklist entry can outlast that — this alone doesn’t guarantee recovery. SourceUnparsable means the source answered but the bundle no longer carries the field the parser looks for, which points at the source having changed shape rather than a transient condition; a later connect can still resolve it, e.g. if the change reverts, but it’s the more likely one to need attention (a version pin via with_version, or a library update).

The server tolerates an app version some days behind current, which is what makes connecting on a fallback a real option rather than a guess. A consumer that can’t accept a stale version, or wants its own policy, can check app_version_fallback on Connected and warn, refuse the session, or pin a version of its own with with_version.

Leaving passive mode is best effort: a failed set_passive(false) call is only logged, not retried, and the connection is announced anyway. Treat Connected as “the client believes stanzas should be flowing,” not a guarantee the server agrees.

Usage:

Event::Connected(connected) => {
    println!("✅ Connected to WhatsApp");
    if let Some(fallback) = &connected.app_version_fallback {
        eprintln!(
            "connected on a fallback app version {:?} ({:?})",
            fallback.version, fallback.reason
        );
    }
    // Safe to send messages now. The push name and blocklist may still be
    // syncing in the background — watch for AppStateSyncFailed if that gap
    // matters to your use case.
}

Disconnected

Emitted: When the connection ends without the client itself intentionally closing or reconnecting it — covers both a routine server-initiated stream recycle and a genuine transport failure (see reason below to tell them apart)

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct Disconnected {
    pub reason: DisconnectReason,
}

Event::Disconnected(Disconnected::builder().reason(reason).build())

Fields:

reason: DisconnectReason — why the transport ended. Check reason.is_clean_shutdown() to tell a routine server-initiated stream recycle (WhatsApp’s normal reconnect path) apart from a genuine transport failure, without parsing logs. See DisconnectReason for the variants.

Behavior: Client automatically attempts reconnection

Breaking change: Disconnected gained the reason field (previously a unit struct). Disconnected is now #[non_exhaustive] too, so a destructuring pattern needs a .. rest: Event::Disconnected(Disconnected { reason, .. }), or just Event::Disconnected(_).

ConnectFailure

Emitted: When connection fails with a specific reason

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct ConnectFailure {
    pub reason: ConnectFailureReason,
    /// The server's `message` attribute on the `<failure>` stanza, when present.
    pub message: Option<String>,
    pub raw: Option<Node>,
}

#[derive(Debug, Clone, PartialEq, Eq, Copy, Serialize)]
pub enum ConnectFailureReason {
    Generic,                // 400
    LoggedOut,              // 401
    TempBanned,             // 402
    AccountLocked,          // 403 — WA Web REASON_LOCKED (account/device locked)
    UnknownLogout,          // 406
    ClientOutdated,         // 405
    BadUserAgent,           // 409
    CatExpired,             // 413
    CatInvalid,             // 414
    NotFound,               // 415
    ClientUnknown,          // 418
    InternalServerError,    // 500
    Experimental,           // 501
    ServiceUnavailable,     // 503
    Unknown(i32),
}

Breaking change: ConnectFailure.message changed from String (empty-string sentinel when the server omitted the message attribute) to Option<String>, matching the “maybe-absent field is always Option” convention. unwrap_or_default() at a call site becomes .unwrap_or_default() on the Option (same fallback) or, better, match/if let Some(msg) = &failure.message.

Helper methods:

if reason.is_logged_out() {
    // Clear session and re-pair
}

if reason.should_reconnect() {
    // Retry connection
}

The 403 variant was renamed MainDeviceGone → AccountLocked in v0.6 to match WA Web’s REASON_LOCKED semantics (the account/device is locked server-side; a manual unlink arrives as a different reason). It still maps from wire code 403 and reports is_logged_out() == true with no auto-reconnect. Update any match arms referencing the old name.

TemporaryBan

Emitted: When account is temporarily banned

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct TemporaryBan {
    pub code: TempBanReason,
    /// How long the ban lasts — the wire's `expire` is a duration in seconds,
    /// not a deadline.
    pub expire: chrono::Duration,
    /// The server's `message` attribute, when present.
    pub message: Option<String>,
    /// Support/appeal link the official ban screen opens.
    pub url: Option<String>,
    /// The whole `<failure>` stanza.
    pub raw: Option<Node>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub enum TempBanReason {
    SentToTooManyPeople,        // 101
    BlockedByUsers,             // 102
    CreatedTooManyGroups,       // 103
    SentTooManySameMessage,     // 104
    BroadcastList,              // 106
    Unknown(i32),
}

Fields:

code — the ban sub-reason from the code attribute
expire — how long the ban lasts, as a chrono::Duration
message — the server’s free-text detail, when present
url — the support/appeal link the official ban screen opens, when the server sent one
raw — the whole <failure> stanza

Breaking change: TemporaryBan gained message, url and raw. It also gained a stricter emission rule: a <failure reason="402"> missing code or expire — or whose expire doesn’t fit a chrono::Duration — no longer dispatches TemporaryBan with an invented zero expiry. Such a stanza now surfaces as ConnectFailure { reason: ConnectFailureReason::TempBanned, raw: Some(node), .. } instead, carrying the same raw stanza. A consumer that matched on Event::TemporaryBan to detect an incomplete ban stanza will now see Event::ConnectFailure.

Usage:

Event::TemporaryBan(ban) => {
    eprintln!("Banned: {} (expires in {:?})", ban.code, ban.expire);
    if let Some(url) = &ban.url {
        eprintln!("Learn more: {url}");
    }
}

StreamReplaced

Emitted: When another device connects with the same credentials (stream error code 409 or <conflict type="replaced">)

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct StreamReplaced {}

Usage:

Event::StreamReplaced(_) => {
    println!("⚠️ Another instance connected - disconnecting");
    // Auto-reconnect is disabled — reconnecting would displace the other client
}

Behavior: Auto-reconnect is disabled. The client stops permanently.

LoggedOut

Emitted: When the session is invalidated by the server (stream error code 401 or 516) or when client.logout() is called

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct LoggedOut {
    pub on_connect: bool,
    pub reason: ConnectFailureReason,
    /// Server-supplied logout copy, when it sent any. Present in practice on
    /// `ConnectFailureReason::AccountLocked`.
    pub logout_message: Option<LogoutMessage>,
    /// The stanza that caused the logout, when one was received.
    pub raw: Option<Node>,
}

/// Localized text the server wants shown when it forces a logout, from
/// `logout_message_header` / `logout_message_subtext` on `<failure>`.
#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct LogoutMessage {
    pub header: Option<String>,
    pub subtext: Option<String>,
    /// e.g. `"pt_BR"`. Compare against the consumer's locale before rendering.
    pub locale: Option<String>,
}

Fields:

on_connect — true if the logout happened during a connection attempt (server-initiated), false if triggered by client.logout() or a stream error while connected
reason — The reason for the logout (e.g., ConnectFailureReason::LoggedOut)
logout_message — server-supplied header/subtext/locale, when the server sent any (in practice, only on an account lock). The official client only renders header/subtext when locale matches the consumer’s current locale, and the locale travels with the text so a consumer can apply the same rule.
raw — the stanza that caused the logout, when one was received. Two different shapes reach this field, so dispatch on raw.tag rather than assuming one: "failure" for a server-side connect refusal (on_connect is then true), and "stream:error" for a <conflict>, a 516 device removal, or a 401 stream error while already connected. None for a locally initiated client.logout() — there’s no stanza to report.

Breaking change: LoggedOut gained logout_message and raw. An account lock (reason: ConnectFailureReason::AccountLocked) carries a server-issued appeal_token plus violation_reason and vt on the <failure> stanza — WA Web itself ignores these (its appeal flow is native-client only) so they aren’t parsed into typed fields, but they now survive on logout.raw for an embedder that wants to build its own appeal UI. Read them off raw.attrs.get("appeal_token"), etc.

Usage:

Event::LoggedOut(logout) => {
    eprintln!("Logged out (reason: {:?})", logout.reason);
    if let Some(msg) = &logout.logout_message {
        eprintln!("Server message: {:?} / {:?}", msg.header, msg.subtext);
    }
    // Session is invalid — you must re-pair the device
    // Auto-reconnect is disabled
}

Behavior: Auto-reconnect is disabled. The application must re-pair the device to establish a new session.

StreamError

Emitted: For unrecognized stream error codes (codes not matching 401, 409, 429, 503, 515, or 516), and — since #1263 — also for 429 (rate-limited), even though 429 is itself a recognized, explicitly-handled code. WhatsApp Web’s own handler has no arm for it either (only 500..600 is special-cased there), so reporting 429 here is an embedder-facing choice rather than a fidelity fix.

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct StreamError {
    pub code: String,
    pub raw: Option<Node>,
}

Usage:

Event::StreamError(err) => {
    eprintln!("Stream error: {} (raw: {:?})", err.code, err.raw);
}

Specific stream error codes have the following event behavior:

401 → LoggedOut (session invalidated)
409 → StreamReplaced (another client connected)
429 → StreamError (rate limited; also reconnects with extended backoff)
503 → No event emitted (reconnects with normal backoff)
515 → No event emitted (immediate reconnect, e.g., after pairing)
516 → LoggedOut (device removed)

Pairing Events

PairingQrCode

Emitted: For each QR code in rotation

/// A QR code the consumer renders during multi-device pairing.
#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PairingQrCode {
    /// The QR payload to render — ASCII art QR or data string.
    pub code: String,
    /// How long this code stays valid before the next one rotates in (60s first, 20s subsequent).
    pub timeout: std::time::Duration,
}

Example:

Event::PairingQrCode(PairingQrCode { code, timeout, .. }) => {
    println!("Scan this QR (valid {}s):", timeout.as_secs());
    println!("{}", code);
}

Breaking change: PairingQrCode moved from inline fields directly on the Event::PairingQrCode { code, timeout } variant to a dedicated sealed struct — Event::PairingQrCode(PairingQrCode). Update destructuring patterns to match through the newtype, with a .. rest since the inner struct is #[non_exhaustive].

PairingCode

Emitted: When pair code is generated

/// Generated pair code for phone number linking.
/// User should enter this code on their phone in WhatsApp > Linked Devices.
#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PairingCode {
    /// The 8-character pairing code to display.
    pub code: String,
    /// Approximate validity duration (~180 seconds).
    pub timeout: std::time::Duration,
}

timeout is the remaining validity window, not always the full ~180 seconds: the clock starts before the stage-1 companion_hello round-trip, so timeout is already reduced by however long that request took.

Example:

Event::PairingCode(PairingCode { code, .. }) => {
    println!("Enter {} on your phone", code);
}

Breaking change: PairingCode moved from inline fields on Event::PairingCode { code, timeout } to a dedicated sealed struct — Event::PairingCode(PairingCode).

PairingCodeRefresh

Emitted: When the in-progress phone-number pairing code should be replaced. Covers two triggers (WA Web Alt/DeviceLinkingApi.js + Link/DevicePhoneNumberCodeScreen.react.js): the server asking for it (refreshAltLinkingCode / forceManualRefresh, only while a pair-code flow is outstanding and the server’s ref matches it — a refresh_code notification for a stale or unrelated flow is silently ignored), and a non-refused companion_finish — accepted, or its own 30s wait going unanswered — whose pair-success then went unanswered for a minute (PairCodeUtils::primary_hello_pair_success_timeout()) — a primary that could not open the key bundle just goes quiet at that point, so silence is the only signal there is. A companion_finish the server actively refuses is a different case and does not fire this event — see PairingCodeError below.

/// The in-progress phone-number pairing code should be replaced.
///
/// Emitted for the two cases WA Web regenerates on: the server asking for it
/// (`refreshAltLinkingCode` / `forceManualRefresh`, ref-gated against the
/// outstanding flow), and pair-success going unanswered after a
/// non-refused `companion_finish` (accepted, or itself unanswered).
///
/// The outstanding flow is cleared before this fires, so the consumer can call
/// `pair_with_code` straight away. The previous code is no longer valid.
#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PairingCodeRefresh {
    /// `true` when the server set `force_manual_refresh` — the code must be
    /// re-requested explicitly rather than auto-rotated. Always `false` for
    /// the silent-`pair-success` timeout trigger.
    pub force_manual: bool,
}

Example:

Event::PairingCodeRefresh(PairingCodeRefresh { force_manual, .. }) => {
    // The previous code is no longer valid, and the flow is already clear —
    // request a new one, e.g. by calling `client.pair_with_code(options)` again.
    println!("Pair code needs a refresh (force_manual={force_manual})");
}

Breaking change: PairingCodeRefresh moved from an inline Event::PairingCodeRefresh { force_manual } field to a dedicated sealed struct — Event::PairingCodeRefresh(PairingCodeRefresh). A matches! check on the field becomes matches!(event, Event::PairingCodeRefresh(r) if r.force_manual).

The silent-pair-success timeout trigger (formerly described as the “unanswered-companion_finish” trigger) is not new by itself. What changed is narrower, but worth registering a handler for: a companion_finish the server actively refuses used to go unanswered like any other stage-2 failure, so it also fell into this same one-minute timeout and eventually fired PairingCodeRefresh. It no longer does — a refusal now exits immediately as PairingCodeError instead (see below) and this event never fires for it. If your handler only registers on_pair_code_refresh (not on_pair_code_error) and relied on it eventually firing for every stage-2 failure, including a refusal, it will now miss that case — the retry will not happen unless you also handle PairingCodeError. A handler that only cares about a server-requested refresh, or that already registers both, needs no changes.

PairingCodeError

Emitted: When a phone-number pair-code flow fails, so no linking will come of it. For a stage-1 failure, Client::pair_with_code dispatches this in addition to returning Err — the event is the only surface that reports it when pairing is driven by BotBuilder::with_pair_code, since that request runs in a detached task and its Err reaches no caller. For a stage-2 companion_finish refusal there is no Err to receive either way: pair_with_code’s call already returned Ok(code) once stage 1 succeeded, long before the notification that drives stage 2 arrives — this event is the only surface for that failure, for a direct caller and a with_pair_code consumer alike.

/// A phone-number pair-code flow failed, so no linking will come of it.
///
/// Fires for every stage-1 failure, including local validation (a too-short
/// phone number never reaches the server), and — since the `companion_finish`
/// round trip started waiting for its answer — for a stage-2 refusal too. Both
/// round trips report through the same event because the consumer's move is
/// the same either way: this code is finished, request another or fall back to
/// the QR. Silence at stage 2 is not this event, because nothing was refused;
/// it surfaces as `PairingCodeRefresh` once the one-minute `pair-success` timer
/// runs out.
#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PairingCodeError {
    /// The server's refusal, when it answered with one. `None` when the
    /// failure was local (validation, no connection) or the request went
    /// unanswered (timeout) — nothing was refused, so there is no status to
    /// report.
    pub rejection: Option<PairCodeRejection>,
    /// How long the server asked the client to wait, from the `backoff`
    /// attribute. Usually absent.
    pub backoff: Option<std::time::Duration>,
    /// The failure rendered for logs. Do not branch on it; use `rejection`.
    pub error: String,
}

Example:

Event::PairingCodeError(PairingCodeError { rejection, backoff, error, .. }) => {
    eprintln!("Pair code request failed: {error}");
    if rejection.is_some_and(PairCodeRejection::is_throttled) {
        // Back off, then retry — using the server's own delay when it named one.
    }
}

Two failures never reach this event, because for them a code may still be on its way and the event would say the opposite: PairCodeError::CodeAlreadyOutstanding (an earlier code is still live — the consumer already has it from the PairingCode that minted it) and PairCodeError::Cancelled (the caller withdrew this request, and a replacement may already own the slot by the time it resolves). Both are consequences of something the caller did, so neither is news to them, and a direct caller still receives the Err either way. See Pair code failure events for PairCodeRejection’s variants and the full breakdown, and BotBuilder::on_pair_code_error to register a handler.

New: this event now also fires for a refused companion_finish (stage 2), reported the moment the server answers rather than after the one-minute pair-success silence timer. No shape change — PairingCodeError’s fields are the same — so a handler already matching on this event needs no code changes, only the awareness that it can now fire earlier and for a second reason. rejection follows companion_finish’s own narrower set of refusals; see PairCodeRejection.

PairingQrCodesExhausted

Emitted: When the server’s <pair-device> refs are used up — there is no QR left to render until the connection is re-established. WA Web’s rotation timer (Handle/PairDevice.js) reports UNPAIRED_IDLE here and stops; it does not close the socket unconditionally, because a phone-number (pair-code) flow may still be riding the same connection.

/// The server's `<pair-device>` refs are used up: there is no QR left to
/// render until the connection is re-established.
#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PairingQrCodesExhausted {
    /// `true` when the client closed the connection itself, which it only does
    /// with no pair-code flow outstanding. `false` means the socket was left
    /// up and reconnecting is the consumer's call.
    pub disconnected: bool,
}

Example:

Event::PairingQrCodesExhausted(PairingQrCodesExhausted { disconnected, .. }) => {
    if disconnected {
        // No pair-code flow was outstanding, so the client is tearing its own
        // socket down and won't auto-reconnect. As of PR #1258, disconnect()
        // is final on this Client instance — build a fresh one against the
        // same persistence_manager and call connect() on it for a fresh
        // batch of refs.
        println!("QR refs exhausted, disconnecting — build a fresh Client to retry");
    } else {
        // A pair-code flow is still outstanding, so the socket is being left
        // up to keep carrying it. There is simply no QR to show right now.
        println!("QR refs exhausted, but a pair code is still in progress");
    }
}

See QR ref exhaustion for why this no longer disconnects unconditionally.

disconnected: true reports intent, not a completed action: the client dispatches this event before awaiting disconnect(), so the socket may still be open at the moment a handler observes it. A synchronous EventHandler runs inline ahead of the disconnect; a Bot/on_event closure runs off a channel on its own task and can race it either way. No Event::Disconnected follows, though: disconnect() sets expected_disconnect, and Disconnected is scoped to disconnects the client did not itself intend, so waiting on it here hangs forever. disconnect() also disables auto-reconnect and, as of PR #1258, is final for this Client instance — it fires the same sticky shutdown signal connect() now checks, so a later connect() on the same instance returns ConnectError::Shutdown rather than eventually succeeding. Build a fresh Client against the same persistence_manager and call connect() on that one instead.

This is a new event and a new EventKind variant, added at the end of EventKind (after ServerAck) rather than next to Event::PairingQrCodesExhausted — new kinds always go at the end, since the discriminant is what a consumer persists or transmits and inserting in the middle would renumber every kind after it.

PairSuccess

Emitted: When pairing completes successfully

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PairSuccess {
    pub id: Jid,
    pub lid: Jid,
    pub business_name: String,
    pub platform: String,
}

Example:

Event::PairSuccess(info) => {
    println!("✅ Paired as {}", info.id);
    println!("LID: {}", info.lid);
    println!("Name: {}", info.business_name);
}

PairError

Emitted: When pairing fails

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PairError {
    pub id: Jid,
    pub lid: Jid,
    pub business_name: String,
    pub platform: String,
    pub error: String,
}

PairPasskeyRequest

Requires the passkey feature (opt-in, off by default as of the next release after 0.7.0). Without it, PairPasskeyRequest, PairPasskeyConfirmation, and PairPasskeyError below are never emitted — a passkey_prologue_request notification instead reaches your handler as Event::Notification. See Feature flags and Authentication — Passkey linking.

Emitted: During passkey (SHORTCAKE_PASSKEY) linking, when the server asks for a WebAuthn assertion to gate the link

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PairPasskeyRequest {
    pub request_options_json: String, // verbatim PublicKeyCredentialRequestOptions JSON
}

If a PasskeyAuthenticator is registered via Client::set_passkey_authenticator, the client obtains and sends the assertion automatically; this event is for hosts that drive the WebAuthn ceremony manually. Example:

Event::PairPasskeyRequest(req) => {
    let assertion = my_get_assertion_from_json(&req.request_options_json).await?;
    client.send_passkey_response(assertion).await?;
}

PairPasskeyConfirmation

Emitted: When the passkey link reaches the verification stage

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PairPasskeyConfirmation {
    pub code: String,          // 8-char "XXXX-XXXX" verification code
    pub skip_handoff_ux: bool, // true on a proven re-link: continuity means the code need not be shown
}

Example:

Event::PairPasskeyConfirmation(conf) => {
    if conf.skip_handoff_ux {
        client.send_passkey_confirmation().await?;
    } else {
        println!("Confirm {} matches on your phone", conf.code);
    }
}

PairPasskeyError

Emitted: When a passkey link attempt fails

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PairPasskeyError {
    pub error: String,
    pub continuation: bool, // false = failed during the initial request, true = during continuation/verification
}

QrScannedWithoutMultidevice

Emitted: When a QR code is scanned by a device that does not support multi-device

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct QrScannedWithoutMultidevice {}

Usage:

Event::QrScannedWithoutMultidevice(_) => {
    println!("QR scanned but device does not support multi-device");
    // Prompt the user to update their WhatsApp app
}

ClientOutdated

Emitted: When the server rejects the connection because the client version is too old (connect failure code 405)

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct ClientOutdated {
    /// The whole `<failure>` stanza, so no attribute is lost to a log line.
    pub raw: Option<Node>,
}

Fields:

raw — the <failure reason="405"> stanza the server sent

Breaking change: ClientOutdated gained raw, carrying the full <failure> stanza instead of discarding it.

Usage:

Event::ClientOutdated(_) => {
    eprintln!("Client version is outdated — update whatsapp-rust");
    // Auto-reconnect is disabled
}

Behavior: Auto-reconnect is disabled. You must update to a newer version of the library.

Message Events

Messages

Emitted: For all incoming messages (text, media, etc.), one event per durable commit.

Event::Messages(MessageBatch)

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct InboundMessage {
    pub message: Arc<wa::Message>,
    pub info: Arc<MessageInfo>,
    /// Disappearing-message timer of the chat this message arrived in, in
    /// seconds, when the stanza carried one.
    pub ephemeral_expiration: Option<u32>,
    /// For a decrypted newsletter comment, the key of the post it replies to.
    /// `None` for every other message.
    pub comment_target: Option<Box<wa::MessageKey>>,
}

pub enum BatchOrigin {
    Live,          // delivered immediately, batch of one
    OfflineDrain,  // accumulated batch from the offline drain
}

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct MessageBatch {
    pub messages: Arc<[InboundMessage]>,
    pub origin: BatchOrigin,
    #[builder(default)]
    pub hook_committed: bool,
}

Live traffic dispatches a batch of one, so per-message latency is unchanged from the previous single-message event. During the offline drain the client accumulates decrypted messages and dispatches one Event::Messages per durable commit (size/byte/timeout triggers, matching WhatsApp Web’s MessageProcessorCache — see Inbound Durability). MessageBatch behaves as a collection: batch.iter(), batch.len(), batch.is_empty(), batch.first(), and for msg in &batch all work directly. Event::as_messages() returns Option<&MessageBatch>, and Event::messages() returns an iterator over the batch’s InboundMessages (empty for any other event kind) — use it to scan a mixed event stream without matching on Event::Messages first.

hook_committed is true when a registered inbound durability hook already committed this batch before it was dispatched. It defaults to false via the builder, so existing .build() calls compile unchanged. It’s a signal for another consumer of the same event stream — not an instruction to skip anything on its own, since a hook that persists elsewhere would leave that consumer as the only materializer. An application-level store that also materializes this same event stream can use it to avoid double-processing a hook-fed batch.

Breaking change: InboundMessage and MessageBatch are now #[non_exhaustive], sealed with a bon builder. A for InboundMessage { message, info } in batch.iter() destructuring pattern needs a .. rest: for InboundMessage { message, info, .. } in batch.iter().

Breaking change: ephemeral_expiration and comment_target moved from MessageInfo onto InboundMessage. Some code samples below may still show info.ephemeral_expiration / info.comment_target from before this change.Writing these fields into the shared MessageInfo needed an Arc::make_mut copy of the whole struct on every message in a disappearing chat. Moving them onto the event, which is already built fresh per dispatch, avoids that copy and lets info stay a cheap shared Arc.Read them by destructuring the field directly off InboundMessage instead of off info: for InboundMessage { comment_target, .. } in batch.iter().MessageContext carries both fields too. MessageContext::from_inbound — what Bot::on_message uses internally — copies them from the event, so a bot handler can read ctx.ephemeral_expiration / ctx.comment_target directly.

Both the message body and MessageInfo are Arc-wrapped inside InboundMessage. The same Arc slice handed to a registered durability hook is what this event carries — no deep clone, and a consumer never sees a message the hook did not commit (newsletter messages and PDO placeholder recoveries are the two exceptions: they dispatch event-only, bypassing the hook). Before v0.6 the body was Box<wa::Message>; the public guarantee changed from “owned, freely mutable” to “shared, immutable read access” — call Arc::make_mut (or clone the inner wa::Message) only if you genuinely need to mutate.

Resend collapse. A sender whose network is bad can retry its own outbox, resending one message re-encrypted under a new sender-key iteration — the Signal ratchet decrypts it cleanly, since it isn’t byte-identical to the first delivery, so nothing at that layer catches it. Since #1352, such a resend collapses to a single Event::Messages dispatch, keyed by chat, message id and sender (device dropped), for as long as the dispatched_messages cache window holds (default 5-minute TTL, 1,000 entries — see cache configuration reference). stats().messages_suppressed_duplicate counts what this collapses. The gate is in-memory only and does not survive a restart of your process, so a hook or consumer performing side effects still needs its own idempotency — see Event::Messages is at-least-once too. It also does not cover a message delivered as several msmsg parts under one stanza id (e.g. a bot streaming a multi-part reply): each part still dispatches, since collapsing there could drop a part the consumer never got.

MessageInfo structure:

#[derive(Debug, Clone, Default, Serialize)]
pub struct MessageInfo {
    pub source: MessageSource,
    pub id: MessageId,
    pub server_id: MessageServerId,
    pub r#type: Option<StanzaMessageType>,
    pub push_name: String,
    pub timestamp: DateTime<Utc>,
    pub server_timestamp_us: Option<i64>,
    pub category: MessageCategory,
    pub multicast: bool,
    pub media_type: Option<EncMediaType>,
    pub edit: EditAttribute,
    pub bot_info: Option<MsgBotInfo>,
    pub meta_info: MsgMetaInfo,
    pub verified_name: Option<Box<VerifiedName>>,
    pub verified_level: Option<String>,
    pub verified_name_serial: Option<String>,
    pub device_sent_meta: Option<DeviceSentMeta>,
    pub is_offline: bool,
    pub peer_recipient_pn: Option<Jid>,
    pub unavailable_request_id: Option<String>,
}

#[derive(Debug, Clone, Default, Serialize)]
pub struct MessageSource {
    pub chat: Jid,             // Where it was sent (group or DM)
    pub sender: Jid,           // Who sent the message
    pub is_from_me: bool,
    pub is_group: bool,
    pub addressing_mode: Option<AddressingMode>,
    pub sender_alt: Option<Jid>,
    pub recipient_alt: Option<Jid>,
    pub broadcast_list_owner: Option<Jid>,
    pub recipient: Option<Jid>,
}

sender_alt carries the LID/PN counterpart of sender whenever the stanza exposes one — including status@broadcast messages, which always include participant_lid (or participant_pn for LID-addressed status). The library reads it unconditionally so the LID-PN cache can re-warm from the message itself, matching WA Web’s WAWebMsgParser.

Breaking change: MessageInfo::r#type changed from String to Option<StanzaMessageType>, and MessageInfo::media_type changed from String to Option<EncMediaType>. Migrate a comparison like info.r#type == "text" to info.r#type == Some(StanzaMessageType::Text), or keep comparing strings with info.r#type.as_ref().map(StanzaMessageType::as_str) == Some("text") — same shape for media_type with EncMediaType. Code that previously treated "" as “absent” now matches None instead.

StanzaMessageType: The <message type="…"> envelope attribute, parsed before any <enc> is decrypted. None when the stanza carried no type attribute at all; an unrecognized value is preserved as Unknown rather than dropped.

pub enum StanzaMessageType {
    Text,             // "text"
    Media,            // "media"
    MediaNotify,      // "medianotify"
    Pay,              // "pay"
    Poll,             // "poll"
    Reaction,         // "reaction"
    Event,            // "event"
    Unknown(String),  // Forward-compatible fallback, holds the raw wire value
}

StanzaMessageType says nothing about the decrypted content — it is the envelope’s own claim, and nothing verifies it against the Message that comes out of the ciphertext.

EncMediaType: The mediatype attribute of an <enc> node — a hint about the payload the ciphertext carries, available before the decryption that would reveal it. MessageInfo::media_type aggregates this across the stanza’s <enc> nodes: the first one that declares a value wins (direct children first, then this device’s own <enc> under <participants>); a later disagreeing value is dropped. None when no <enc> carried the attribute.

pub enum EncMediaType {
    Image, Video, Ptv, Audio, Ptt, Location, Vcard, Document, Url, Call,
    Gif, Future, ContactArray, LiveLocation, ProfilePic, Sticker,
    StickerPack, Hsm, ProductImage, Template, MdAppState, MdHistorySync,
    List, ListResponse, Button, ButtonResponse, Order, Product,
    NativeFlowResponse, GroupHistory,
    Unknown(String),  // Forward-compatible fallback, holds the raw wire value
}

It is the sender’s claim and nothing checks it against the decrypted Message, so it is useful for routing and telemetry, not for deciding what a message is. MessageInfo::media_type is aggregated to one value per message — a fan-out stanza’s per-device <enc> copies all repeat the same attribute in practice, so the aggregation only fills the field when the direct children carry nothing.

MessageCategory:

pub enum MessageCategory {
    Empty,        // Default (empty string on the wire)
    Peer,         // Self-synced message from primary phone
    Other(String), // Unknown category (forward compatibility)
}

EditAttribute: Indicates the type of edit or revocation applied to a message. Values correspond to the wire-format edit attribute on message stanzas.

pub enum EditAttribute {
    Empty,            // "" — no edit (default)
    MessageEdit,      // "1" — message text was edited
    PinInChat,        // "2" — message was pinned/unpinned
    AdminEdit,        // "3" — admin edited the message
    SenderRevoke,     // "7" — sender deleted for everyone
    AdminRevoke,      // "8" — admin deleted for everyone
    Unknown(String),  // Forward-compatible fallback
}

MsgBotInfo: Present when the message originates from a WhatsApp bot (AI-generated responses). Contains streaming edit metadata.

pub struct MsgBotInfo {
    pub edit_type: Option<BotEditType>,
    pub edit_target_id: Option<MessageId>,
    pub edit_sender_timestamp_ms: Option<DateTime<Utc>>,
}

pub enum BotEditType {
    First,  // Initial bot response
    Inner,  // Streaming update (intermediate chunk)
    Last,   // Final streaming update
}

MsgMetaInfo: Additional metadata for message threading, targeting, and abuse reporting.

pub type ReportingBytes = SmallVec<[u8; 20]>;

pub struct MsgMetaInfo {
    pub target_id: Option<CompactString>,
    pub target_sender: Option<Jid>,
    pub thread_message_id: Option<CompactString>,
    pub thread_message_sender_jid: Option<Jid>,
    pub poll_type: Option<PollType>,
    pub content_type: Option<CompactString>,
    pub appdata: Option<CompactString>,
    pub reporting_tag: Option<ReportingBytes>,
    pub reporting_token: Option<ReportingBytes>,
    pub reporting_token_version: Option<i64>,
}

Breaking change (whatsapp-rust#1343): target_id and thread_message_id changed from Option<MessageId> to Option<CompactString>. content_type and appdata changed from Option<String> to Option<CompactString>. CompactString (wacore_binary::CompactString) stores up to 24 bytes inline on 64-bit targets, with a smaller inline limit on 32-bit/wasm32 — a message id and these short keywords fit inline on 64-bit.reporting_tag and reporting_token changed from Option<Vec<u8>> to Option<ReportingBytes>, a new SmallVec<[u8; 20]> alias. It keeps a 16-or-20-byte tag or a 16-byte token inline; a payload wider than 20 bytes still spills to the heap.Read-only access — comparisons, .as_deref(), formatting — is unaffected, since both types deref to &str/&[u8]. A call site that assigns these fields from a String/Vec<u8> literal, or moves a value out into one, needs one .into() per site (.to_vec() for ReportingBytes → Vec<u8>).

Field	Description
`target_id`	ID of the message being targeted (for edits/revokes)
`target_sender`	Sender of the targeted message
`thread_message_id`	ID of the message this one threads under (`<meta thread_msg_id="…">`)
`thread_message_sender_jid`	Who authored `thread_message_id`; absent whenever that is
`poll_type`	Which stage of a poll’s lifecycle the envelope carries (`<meta polltype="…">`); see `PollType` below
`content_type`	High-level content classification carried by the server (e.g. `"image"`, `"document"`) so consumers can filter without decoding the message body
`appdata`	Opaque per-message app data used by the abuse-report flow
`reporting_tag`	Tag the server attaches so the recipient can submit an abuse report tied to this message
`reporting_token`	Raw bytes of the abuse-report token paired with `reporting_tag`
`reporting_token_version`	Version of the reporting-token scheme used by the server

PollType: Read only when the envelope’s r#type is StanzaMessageType::Poll, mirroring the official WhatsApp Web parser, which scopes the polltype attribute to poll envelopes. Closed on purpose — a polltype value outside this list parses as None rather than being preserved as an Unknown variant, since upstream treats it the same way.

pub enum PollType {
    Creation,       // "creation"
    QuizCreation,   // "quiz_creation"
    Vote,           // "vote"
    ResultSnapshot, // "result_snapshot"
    Edit,           // "edit"
}

server_timestamp_us, verified_level, verified_name_serial, peer_recipient_pn, plus target_id, target_sender, thread_message_id, thread_message_sender_jid, content_type, appdata, reporting_tag, reporting_token, and reporting_token_version on MsgMetaInfo were added in v0.6 as part of aligning inbound parsing with WA Web. They are populated only when the server includes the corresponding stanza attribute, so existing consumers that ignore them keep working.

Breaking change: MsgMetaInfo::deprecated_lid_session was removed. It was declared but never assigned by any parser, and no wire attribute maps to it — nothing to migrate to, callers should simply drop the field access.thread_message_id and thread_message_sender_jid were already declared before this change but always empty; they are now actually populated, sourced from the poll envelope’s thread_msg_id / thread_msg_sender_jid attributes. poll_type is new, sourced from <meta polltype="…"> and scoped to StanzaMessageType::Poll envelopes only.

Breaking change: verified_name changed from the raw, never-populated wa::VerifiedNameCertificate to Option<Box<VerifiedName>> — the decoded business display name (see VerifiedName for its name/serial/issuer/certificate fields). Business senders attach this cert to the <message> stanza’s <verified_name> child; it’s now decoded the same way the usync and business-notification parsers already did, so a WABA sender’s display name (e.g. “HDFC Bank Ltd”) reaches this field instead of being silently dropped. It’s boxed since most messages carry none. Undecodable cert bytes don’t fail message parsing — the field is just None in that case.verified_name_serial is unrelated to and unchanged by this: it’s parsed from the envelope’s own verified_name attribute (an integer), while verified_name.serial is decoded from the child cert’s Details.serial field (a string). Both name the same certificate serial in a well-formed stanza, but they’re read from two different places on the wire and can be populated independently — a stanza could in principle carry one without the other.

Every Option<T> field on MessageInfo, MessageSource, MsgBotInfo, and MsgMetaInfo is annotated #[serde(skip_serializing_if = "Option::is_none")]. A JSON serialization of these structs (e.g. via serde_json::to_value, for structured logging or observability dumps) omits an absent field entirely instead of emitting it as null. This applies uniformly across all optional fields as of the allocation/serialization cleanup in whatsapp-rust#1059 — earlier releases only omitted the four v0.6-era fields above, and serialized the remaining optional fields as explicit null when absent. Present field values are unchanged; only the JSON output shape for absent fields differs.

DeviceSentMeta: Present on device-synced messages (messages you sent from another device).

pub struct DeviceSentMeta {
    pub destination_jid: String,
    pub phash: String,
}

Example:

use waproto::whatsapp as wa;

Event::Messages(batch) => {
    for InboundMessage { message: msg, info, .. } in batch.iter() {
        println!("From: {} in {}", info.source.sender, info.source.chat);

        // Text message
        if let Some(text) = &msg.conversation {
            println!("Text: {}", text);
        }

        // Extended text (with link preview, quoted message, etc.)
        if let Some(ext) = &msg.extended_text_message {
            println!("Text: {}", ext.text.as_deref().unwrap_or(""));

            if let Some(context) = &ext.context_info {
                if let Some(quoted) = &context.quoted_message {
                    println!("Quoted: {:?}", quoted);
                }
            }
        }

        // Image message
        if let Some(img) = &msg.image_message {
            println!("Image: {} ({}x{})", 
                img.caption.as_deref().unwrap_or(""),
                img.width.unwrap_or(0),
                img.height.unwrap_or(0)
            );
        }

        // Video, audio, document, sticker, etc.
        // See waproto::whatsapp::Message for all types
    }
}

Receipt

Emitted: For delivery/read/played receipts

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct Receipt {
    pub source: MessageSource,
    pub message_ids: Vec<MessageId>,
    pub timestamp: DateTime<Utc>,
    pub r#type: ReceiptType,
    /// `true` when the receipt was drained from the server's offline queue on
    /// reconnect (carried the `offline` attribute) rather than delivered live.
    pub offline: bool,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[non_exhaustive]
pub enum ReceiptType {
    Delivered,
    Sender,
    Retry,
    EncRekeyRetry,
    Read,
    ReadSelf,
    Played,
    PlayedSelf,
    ServerError,
    Inactive,
    PeerMsg,
    HistorySync,
    Other(String),
}

ReceiptType is #[non_exhaustive]. Server-driven sets like this grow over time (recent additions include EncRekeyRetry, ReadSelf, PlayedSelf, PeerMsg, and HistorySync), so your match arms must always include a wildcard (_ => …). New variants can be added in minor releases without a breaking change.

Example:

Event::Receipt(receipt) => {
    match receipt.r#type {
        ReceiptType::Read => {
            println!("✓✓ Read by {}", receipt.source.sender);
        }
        ReceiptType::Delivered => {
            println!("✓ Delivered to {}", receipt.source.sender);
        }
        _ => {}
    }
}

UndecryptableMessage

Emitted: When a message cannot be decrypted or is unavailable. This includes:

Decryption failures (no session, invalid keys, MAC errors)
Group messages that fail with NoSenderKeyState (missing sender key) — dispatched before the retry receipt is sent
Messages with an <unavailable> node — view-once already viewed, hosted content, bot fanouts, or other server-side unavailability. For ViewOnce/Hosted/Bot, the phone never shares that content with a companion device, so the client acks the stanza directly instead of requesting it. Only the Unknown case goes through PDO recovery

When is_unavailable is true, the message had no encrypted content in the stanza. For UnavailableType::Unknown, the client sends a PDO request to your primary phone, and if the phone responds successfully, a follow-up Event::Messages is dispatched with the recovered content (event-only — a PDO recovery bypasses the durability hook and the offline-drain batcher, dispatching immediately with BatchOrigin::Live). For ViewOnce, Hosted, and Bot, no PDO request is sent — that content is unrecoverable by design, so no follow-up Event::Messages should be expected.

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct UndecryptableMessage {
    pub info: Arc<MessageInfo>,
    pub is_unavailable: bool,
    pub unavailable_type: UnavailableType,
    pub decrypt_fail_mode: DecryptFailMode,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub enum UnavailableType {
    Unknown,
    ViewOnce,       // View-once media already viewed
    Hosted,         // Hosted content the phone won't fan out to companions
    Bot,            // AI bot message fanout
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub enum DecryptFailMode {
    Show,           // Show placeholder in chat
    Hide,           // Hide from chat
}

The client deduplicates dispatch per (chat, id, sender), not (chat, id) alone. A stanza id comes from the sending client. That id is only unique within a (chat, sender) pair. So two different senders can reuse the same id in one chat. The client treats those as two distinct messages and dispatches an event for each, instead of folding the second into the first.The client keys the sender on its wire-form JID. It deliberately leaves that JID unresolved to a LID/PN identity, because resolving it would let the key move as the client learns that mapping at runtime. This choice has one accepted cost: if a redelivery’s sender switches PN/LID namespace mid-flight, the client treats it as a new message and dispatches a second placeholder. The client accepts that cost because a duplicate placeholder is visible and recoverable, while a silently dropped message is not.The dedup cache holds each key for up to 5 minutes (a TTL measured from first dispatch), or until it evicts the key to stay under its 1,000-entry capacity — whichever comes first. Once a key leaves the cache, a later redelivery of that same message dispatches the event again.

Notification

Emitted: For raw notification stanzas that are not handled by a more specific event type

Event::Notification(Arc<OwnedNodeRef>)

This is a passthrough event that gives you access to the raw node for notification types that the library does not parse into dedicated event structs. The OwnedNodeRef provides zero-copy access to the decoded stanza — call .get() to obtain a NodeRef for inspecting the tag, attributes, and children. Example:

Event::Notification(node) => {
    let node_ref = node.get();
    println!("Raw notification tag: {}", node_ref.tag);
}

Most notifications are already parsed into specific event types (e.g., GroupUpdate, DeviceListUpdate, ContactUpdated), and this event otherwise fires only for unhandled notification types. The one exception is groups_dirty: the library both acts on it and forwards it here.

DecryptFailMode is determined by the decrypt-fail attribute on incoming <enc> nodes. If any <enc> node has decrypt-fail="hide", the entire message uses Hide mode.

Show — Default. The application should display a “waiting for this message” placeholder. Used for regular user-visible messages.
Hide — The application should silently discard the failure. Used for infrastructure messages (reactions, poll votes, pin changes, edit messages, event responses, message history notices, secret encrypted event/poll edits, certain protocol messages, and SKDM stanzas) that don’t need user-visible placeholders.

See Decrypt-fail suppression for the full list of message types that set this attribute on outgoing stanzas. Example:

Event::UndecryptableMessage(undec) => {
    match undec.decrypt_fail_mode {
        DecryptFailMode::Hide => {
            // Silently ignore — infrastructure message (reaction, poll vote, etc.)
        }
        DecryptFailMode::Show => {
            match undec.unavailable_type {
                UnavailableType::ViewOnce => println!("View-once message already consumed"),
                UnavailableType::Hosted => println!("Hosted content unavailable"),
                UnavailableType::Bot => println!("Bot message unavailable"),
                UnavailableType::Unknown => {
                    eprintln!("Failed to decrypt message from {}", undec.info.source.sender);
                }
            }
        }
    }
}

ServerAck

Emitted: Observe-only, for every server <ack> stanza that carries an id — dispatched independently of the internal send-waiter resolution, so registering a handler never interacts with the send/phash flow.

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct ServerAck {
    pub id: String,
    pub class: Option<String>,
    pub from: Option<Jid>,
    pub timestamp: Option<DateTime<Utc>>,
    pub error: Option<String>,
}

Field	Description
`id`	Id of the acked stanza (for a sent message, its message id).
`class`	Stanza class the ack refers to (`"message"`, `"receipt"`, `"notification"`, `"call"`, …). `None` when the server omits it.
`from`	Chat/entity the ack refers to, when present and parseable.
`timestamp`	Server timestamp from the ack’s `t` attribute, when present. For a message ack this is the authoritative send timestamp — the same attribute the whatsmeow Go library reads into its own `SendResponse.Timestamp`.
`error`	Nack code (e.g. `"479"`), when the ack is actually a nack; `None` for a plain ack.

Server acks cover every outgoing stanza class, not just messages — filter on class rather than correlating ids blind. Dispatch is gated on a registered handler existing for this event kind, so the hot ack path allocates nothing when no consumer subscribes.

ServerAck was the first payload sealed under the stability policy above: it’s #[non_exhaustive] and constructed via a generated bon builder (ServerAck::builder().id(...).maybe_class(...)…build()). This only affects code that constructs a ServerAck (the client itself) or uses exhaustive struct-pattern destructuring (which is already disallowed by the .. guidance above); accessing fields by name with dot notation (ack.id, ack.class), as in the example below, is unaffected.

Example:

Event::ServerAck(ack) => {
    if ack.class.as_deref() == Some("message") {
        if let Some(err) = &ack.error {
            eprintln!("Message {} nacked: {err}", ack.id);
        } else {
            println!("Message {} accepted by the server", ack.id);
        }
    }
}

Presence Events

ChatPresence

Emitted: For typing indicators and recording states

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct ChatPresenceUpdate {
    pub source: MessageSource,
    pub state: ChatPresence,
    pub media: ChatPresenceMedia,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub enum ChatPresence {
    Composing,
    Paused,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub enum ChatPresenceMedia {
    Text,
    Audio,
}

Example:

Event::ChatPresence(update) => {
    match (update.state, update.media) {
        (ChatPresence::Composing, ChatPresenceMedia::Text) => {
            println!("{} is typing...", update.source.sender);
        }
        (ChatPresence::Composing, ChatPresenceMedia::Audio) => {
            println!("{} is recording audio...", update.source.sender);
        }
        (ChatPresence::Paused, _) => {
            println!("{} stopped typing", update.source.sender);
        }
    }
}

Presence

Emitted: For online/offline status and last seen

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PresenceUpdate {
    pub from: Jid,
    pub unavailable: bool,
    pub last_seen: Option<DateTime<Utc>>,
}

Example:

Event::Presence(update) => {
    if update.unavailable {
        println!("{} is offline", update.from);
        if let Some(last_seen) = update.last_seen {
            println!("Last seen: {}", last_seen);
        }
    } else {
        println!("{} is online", update.from);
    }
}

User update events

PictureUpdate

Emitted: When a user changes their profile picture

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PictureUpdate {
    pub jid: Jid,
    pub author: Option<Jid>,
    pub timestamp: DateTime<Utc>,
    pub removed: bool,
    pub picture_id: Option<String>,
}

Fields:

jid - The JID whose picture changed (user or group)
author - The user who made the change. Present for group picture changes (the admin who changed it). None for personal picture updates.
removed - Whether the picture was removed (true) or set/updated (false)
picture_id - The server-assigned picture ID. None for deletions.

UserAboutUpdate

Emitted: When a user changes their status/about

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct UserAboutUpdate {
    pub jid: Jid,
    pub status: String,
    pub timestamp: DateTime<Utc>,
}

`RetiredPushNameUpdate`

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct RetiredPushNameUpdate {}

Breaking change (PR #1310): this event is retired. Nothing constructs or dispatches it, and nothing ever will. The payload promised an old_push_name/new_push_name comparison, but this library holds no contact store to source the previous name from. EventKind::PushNameUpdate is renamed EventKind::RetiredPushNameUpdate the same way.Both the EventKind and Event variants keep their slot instead of being deleted. EventKind’s discriminant is an EventInterest bit index a consumer may persist. Event derives Serialize into index-keyed formats (bincode, postcard) that key a variant by position. Removing either would renumber every variant after it and change how already-stored data decodes. The payload struct is emptied instead, so the slot is held without claiming anything.A handler matching Event::PushNameUpdate(..) should drop the arm — it can never fire — or rename it to Event::RetiredPushNameUpdate(..).To track a contact’s push name, read MessageInfo::push_name on the message events you already handle. It comes from the stanza’s notify attribute, and a stanza without that attribute (e.g. newsletter traffic) leaves it as an empty string. Treat an empty push_name as “not present,” not as a rename to "", and diff only non-empty values against your own contact store if you need change detection.

SelfPushNameUpdated

Emitted: When your own push name is updated

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct SelfPushNameUpdated {
    pub from_server: bool,
    pub old_name: String,
    pub new_name: String,
}

Group Events

GroupUpdate

Emitted: For each action in a group notification (subject changes, participant changes, settings updates, etc.). A single notification may produce multiple GroupUpdate events.

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct GroupUpdate {
    pub group_jid: Jid,
    pub participant: Option<Jid>,
    pub participant_pn: Option<Jid>,
    pub timestamp: DateTime<Utc>,
    pub is_lid_addressing_mode: bool,
    pub action: Box<GroupNotificationAction>,
}

Fields:

group_jid - The group this update applies to
participant - The admin/user who triggered the change
participant_pn - Phone number JID of the participant (for LID-addressed groups)
is_lid_addressing_mode - Whether the group uses LID addressing mode
action - The specific group notification action (subject change, participant add/remove/promote/demote, description change, etc.). It is boxed, like the action field of every other sync-action event payload (ContactUpdate, PinUpdate, MuteUpdate, …). It was the largest variant of Event, and every dispatched event pays for the size of the largest one.

Example:

Event::GroupUpdate(update) => {
    println!("Group {} updated by {:?}: {:?}", 
        update.group_jid, update.participant, update.action);
}

GroupNotificationAction

The action field on GroupUpdate is a GroupNotificationAction enum with the following variants:

Variant	Wire tag	Description
`Add { participants, reason }`	`<add>`	Members added to group
`Remove { participants, reason }`	`<remove>`	Members removed from group
`Promote { participants }`	`<promote>`	Members promoted to admin
`Demote { participants }`	`<demote>`	Members demoted from admin
`Modify { participants }`	`<modify>`	Member changed phone number
`ChangeNumber { new_owner, sub_group_suggestions }`	`<change_number>`	A participant changed their phone number. `new_owner` is read from the `jid` attribute of `<change_number>` and `sub_group_suggestions` is collected from any `<sub_group_suggestion>` children. The previous JID is carried by `GroupUpdate::participant`.
`Subject { subject, subject_owner, subject_owner_pn, subject_owner_username, subject_time }`	`<subject>`	Group name changed
`Description { id, description }`	`<description>`	Group description changed or deleted
`Locked { threshold }`	`<locked>`	Only admins can edit group info
`Unlocked`	`<unlocked>`	All members can edit group info
`Announce`	`<announcement>`	Only admins can send messages
`NotAnnounce`	`<not_announcement>`	All members can send messages
`Ephemeral { expiration, trigger }`	`<ephemeral>`	Disappearing messages setting changed
`MembershipApprovalMode { enabled }`	`<membership_approval_mode>`	Join approval toggled
`MembershipApprovalRequest { request_method, parent_group_jid }`	`<membership_approval_request>`	A user requested to join the group
`CreatedMembershipRequests { request_method, parent_group_jid, requests }`	`<created_membership_requests>`	Admin-side: new join requests appeared
`RevokedMembershipRequests { participants }`	`<revoked_membership_requests>`	Membership requests rejected or cancelled
`MemberAddMode { mode }`	`<member_add_mode>`	Who can add members (`admin_add` or `all_member_add`)
`NoFrequentlyForwarded`	`<no_frequently_forwarded>`	Forwarding restricted
`FrequentlyForwardedOk`	`<frequently_forwarded_ok>`	Forwarding allowed
`Invite { code }`	`<invite>`	Member joined via invite link
`RevokeInvite`	`<revoke>`	Invite link revoked
`GrowthLocked { expiration, lock_type }`	`<growth_locked>`	Invite links unavailable
`GrowthUnlocked`	`<growth_unlocked>`	Invite links available again
`Create { raw }`	`<create>`	Group created
`Delete { reason }`	`<delete>`	Group deleted
`Link { link_type, raw }`	`<link>`	Subgroup linked (community)
`Unlink { unlink_type, unlink_reason, raw }`	`<unlink>`	Subgroup unlinked (community)
`Unknown { tag }`	varies	Unknown notification tag (forward compatibility)

Participant-related variants include a participants field of type Vec<GroupParticipantInfo>:

pub struct GroupParticipantInfo {
    pub jid: Jid,
    pub phone_number: Option<Jid>,
    pub display_name: Option<String>,
}

display_name carries the server-provided label for a participant — for non-contacts this is typically the masked phone number ("+55•••••••••79"). It is populated only when the participant appears as a <participant> child of a group notification; entries that arrive via <requested_user> (membership requests) leave it None. Subject::subject_owner follows the group’s addressing mode, so in a LID-addressed group it is a @lid JID; the renamer’s phone-number JID arrives separately as subject_owner_pn (from s_o_pn), with subject_owner_username (from s_o_username) when present — the same split GroupUpdate::participant / participant_pn uses. Membership request variants include a request_method field of type MembershipRequestMethod:

pub enum MembershipRequestMethod {
    InviteLink,        // User clicked an invite link
    LinkedGroupJoin,   // User joined via a linked community subgroup
    NonAdminAdd,       // A non-admin member tried to add the user
}

MembershipApprovalRequest — emitted when a user requests to join a group. The requester is identified by the parent GroupUpdate::participant field.
CreatedMembershipRequests — admin-side notification: new join requests appeared. The requests field contains the requesting users (as Vec<GroupParticipantInfo>).
RevokedMembershipRequests — emitted when membership requests are rejected by an admin or cancelled by the requester. The participants field contains the affected JIDs.

Both MembershipApprovalRequest and CreatedMembershipRequests include an optional parent_group_jid field for community-linked joins. Example: handling specific group actions:

use wacore::stanza::groups::GroupNotificationAction;

Event::GroupUpdate(update) => {
    match &*update.action {
        GroupNotificationAction::Add { participants, .. } => {
            for p in participants {
                println!("{} was added to {}", p.jid, update.group_jid);
            }
        }
        GroupNotificationAction::Subject { subject, .. } => {
            println!("Group {} renamed to {}", update.group_jid, subject);
        }
        GroupNotificationAction::Ephemeral { expiration, .. } => {
            if *expiration == 0 {
                println!("Disappearing messages disabled in {}", update.group_jid);
            } else {
                println!("Disappearing messages set to {}s in {}", expiration, update.group_jid);
            }
        }
        GroupNotificationAction::MembershipApprovalRequest { request_method, parent_group_jid } => {
            println!("Join request in {} via {:?}", update.group_jid, request_method);
            if let Some(parent) = parent_group_jid {
                println!("From community: {}", parent);
            }
        }
        GroupNotificationAction::CreatedMembershipRequests { requests, request_method, .. } => {
            println!("{} new join requests in {} via {:?}",
                requests.len(), update.group_jid, request_method);
        }
        GroupNotificationAction::RevokedMembershipRequests { participants } => {
            println!("{} membership requests revoked in {}",
                participants.len(), update.group_jid);
        }
        _ => {}
    }
}

PR #1402 changed GroupUpdate::action to Box<GroupNotificationAction>. At 288 bytes it made GroupUpdate the largest variant of Event, and Event’s size is what every dispatched event’s Arc allocation pays for, group update or not. Field access (update.action.foo) is unchanged. A match on update.action that names a GroupNotificationAction variant now needs match &*update.action { ... }, as in the example below.

A single group notification from the server can contain multiple actions. The library dispatches a separate GroupUpdate event for each action, so your handler may receive multiple events from one notification.

Stale group metadata (`groups_dirty`)

The server can also send <notification type="w:gp2"> wrapping a <groups_dirty> child, naming one or more groups whose cached metadata is now stale (for example, after a bulk membership change made elsewhere). This is not an ordinary group notification — its from is the group server, not a group JID — so it produces no GroupUpdate event. Instead, the library evicts the cached snapshot for each named group and still dispatches the raw stanza as Event::Notification — an exception to that event’s usual “unhandled types only” rule, since the library both acts on groups_dirty (the cache eviction) and forwards it. The next query_info (or a send) for an affected group transparently re-fetches its metadata from the server, since query_info’s default Freshness::CachePreferred behavior only serves the cache when it is populated. You do not need to call query_info_with_freshness(&jid, Freshness::Refresh) yourself in response to this notification — see Cache group information.

Contact notification events

Most events in this section are emitted from <notification type="contacts"> stanzas sent by the server. Two are not: ContactUpdate and ContactRemoved come from app-state sync mutations instead, grouped here with their notification-based siblings because they are all contact-related — each one’s own description below states its actual source.

ContactUpdated

Emitted: When a contact’s profile changes (server notification)

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct ContactUpdated {
    pub jid: Jid,
    pub timestamp: DateTime<Utc>,
}

Wire format: <notification type="contacts"><update jid="..."/> When you receive this event, you should invalidate any cached presence or profile picture data for the contact. WhatsApp Web resets its PresenceCollection and refreshes the profile picture thumbnail on this event. Example:

Event::ContactUpdated(update) => {
    println!("Contact {} profile changed at {}", update.jid, update.timestamp);
    // Invalidate cached presence/profile data
    // Re-fetch profile picture if needed
}

ContactNumberChanged

Emitted: When a contact changes their phone number

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct ContactNumberChanged {
    /// Old phone number JID.
    pub old_jid: Jid,
    /// New phone number JID.
    pub new_jid: Jid,
    /// Old LID (if provided by server).
    pub old_lid: Option<Jid>,
    /// New LID (if provided by server).
    pub new_lid: Option<Jid>,
    pub timestamp: DateTime<Utc>,
}

Wire format: <notification type="contacts"><modify old="..." new="..." old_lid="..." new_lid="..."/> The library automatically creates LID-PN mappings when LID attributes are present (old_lid→old_jid and new_lid→new_jid). WhatsApp Web generates a system notification message in both the old and new chats. Example:

Event::ContactNumberChanged(change) => {
    println!("Contact changed number: {} -> {}", change.old_jid, change.new_jid);
    if let Some(new_lid) = &change.new_lid {
        println!("New LID: {}", new_lid);
    }
    // Update your contact records to use the new JID
}

ContactSyncRequested

Emitted: When the server requests a full contact re-sync

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct ContactSyncRequested {
    /// If present, only sync contacts modified after this timestamp.
    pub after: Option<DateTime<Utc>>,
    pub timestamp: DateTime<Utc>,
}

Wire format: <notification type="contacts"><sync after="..."/> Example:

Event::ContactSyncRequested(sync) => {
    if let Some(after) = sync.after {
        println!("Server requests contact sync for changes after {}", after);
    } else {
        println!("Server requests full contact sync");
    }
}

ContactUpdate

Emitted: When a contact’s information changes via app-state sync (e.g., first name, last name set in your address book)

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct ContactUpdate {
    pub jid: Jid,
    pub timestamp: DateTime<Utc>,
    pub action: Box<wa::sync_action_value::ContactAction>,
    pub from_full_sync: bool,
}

Fields:

jid - The contact whose information changed
timestamp - When the change occurred
action - The contact action from app-state sync, containing fields like full_name and first_name
from_full_sync - Whether this came from a full app-state sync (initial load) or an incremental update

Example:

Event::ContactUpdate(update) => {
    println!("Contact {} updated at {}", update.jid, update.timestamp);
    if let Some(name) = &update.action.full_name {
        println!("Full name: {}", name);
    }
    if update.from_full_sync {
        println!("(from full sync)");
    }
}

ContactUpdate comes from app-state sync mutations and is distinct from ContactUpdated, which comes from server-side <notification type="contacts"> stanzas.

The server may also send <add/> and <remove/> child actions in contacts notifications for lightweight roster changes. These are acknowledged automatically and do not emit events.

ContactRemoved

Emitted: When a saved contact is deleted via app-state sync on a linked device

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct ContactRemoved {
    pub jid: Jid,
    pub timestamp: DateTime<Utc>,
    pub from_full_sync: bool,
}

Fields:

jid - The contact that was removed
timestamp - When the removal occurred
from_full_sync - Whether this came from a full app-state sync (initial load) or an incremental update

Example:

Event::ContactRemoved(update) => {
    println!("Contact {} removed", update.jid);
}

ContactRemoved is distinct from ContactUpdate, and the event itself carries no action payload. The underlying wire mutation is different: it is a syncd Remove with an all-default ContactAction value, since WhatsApp Web builds that value before choosing the operation. WhatsApp Web ignores the value on the Remove branch and simply drops the contact from the address book — but if you call remove_app_state_action directly for an action like this one, you still need to pass a value. See Chat actions — Save and remove contacts for the outbound API (remove_contact) that emits this event on other devices.

Chat state events

PinUpdate

Emitted: When a chat is pinned/unpinned

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct PinUpdate {
    pub jid: Jid,
    pub timestamp: DateTime<Utc>,
    pub action: Box<wa::sync_action_value::PinAction>,
    pub from_full_sync: bool,
}

MuteUpdate

Emitted: When a chat is muted/unmuted

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct MuteUpdate {
    pub jid: Jid,
    pub timestamp: DateTime<Utc>,
    pub action: Box<wa::sync_action_value::MuteAction>,
    pub from_full_sync: bool,
}

ArchiveUpdate

Emitted: When a chat is archived/unarchived

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct ArchiveUpdate {
    pub jid: Jid,
    pub timestamp: DateTime<Utc>,
    pub action: Box<wa::sync_action_value::ArchiveChatAction>,
    pub from_full_sync: bool,
}

StarUpdate

Emitted: When a message is starred or unstarred

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct StarUpdate {
    pub chat_jid: Jid,
    pub participant_jid: Option<Jid>,
    pub message_id: String,
    pub from_me: bool,
    pub timestamp: DateTime<Utc>,
    pub action: Box<wa::sync_action_value::StarAction>,
    pub from_full_sync: bool,
}

Fields:

chat_jid - The chat containing the starred message
participant_jid - The sender of the message (only for group messages from others; None for self-authored or 1-on-1 messages)
message_id - The ID of the starred/unstarred message
from_me - Whether the starred message was sent by you

Example:

Event::StarUpdate(update) => {
    println!("Message {} in {} was {}starred",
        update.message_id, update.chat_jid,
        if update.action.starred.unwrap_or(false) { "" } else { "un" }
    );
}

MarkChatAsReadUpdate

Emitted: When a chat is marked as read or unread across linked devices

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct MarkChatAsReadUpdate {
    pub jid: Jid,
    pub timestamp: DateTime<Utc>,
    pub action: Box<wa::sync_action_value::MarkChatAsReadAction>,
    pub from_full_sync: bool,
}

Example:

Event::MarkChatAsReadUpdate(update) => {
    let read = update.action.read.unwrap_or(false);
    println!("Chat {} marked as {}", update.jid, if read { "read" } else { "unread" });
}

DeleteChatUpdate

Emitted: When a chat is deleted across linked devices

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct DeleteChatUpdate {
    pub jid: Jid,
    /// From the index, not the proto — DeleteChatAction only has messageRange.
    pub delete_media: bool,
    pub timestamp: DateTime<Utc>,
    pub action: Box<wa::sync_action_value::DeleteChatAction>,
    pub from_full_sync: bool,
}

Fields:

jid - The JID of the deleted chat
delete_media - Whether media files were also deleted
action - The underlying protobuf action containing the optional message_range

Example:

Event::DeleteChatUpdate(update) => {
    println!("Chat {} deleted (media deleted: {})", update.jid, update.delete_media);
}

ClearChatUpdate

Emitted: When a chat’s messages are cleared (but the chat is kept) on a linked device

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct ClearChatUpdate {
    pub jid: Jid,
    /// From the index, not the proto — ClearChatAction only has messageRange.
    pub delete_starred: bool,
    /// From the index, not the proto.
    pub delete_media: bool,
    pub timestamp: DateTime<Utc>,
    pub action: Box<wa::sync_action_value::ClearChatAction>,
    pub from_full_sync: bool,
}

Fields:

jid - The chat that was cleared
delete_starred - Whether starred messages were also removed
delete_media - Whether downloaded media was also removed
from_full_sync - true while replaying the initial app state full sync

Example:

Event::ClearChatUpdate(update) => {
    println!("Chat {} cleared (starred: {}, media: {})",
        update.jid, update.delete_starred, update.delete_media);
}

See clear_chat for the outbound API that emits this on other devices.

UserStatusMuteUpdate

Emitted: When a contact/group/channel’s status updates are muted or unmuted on a linked device

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct UserStatusMuteUpdate {
    pub jid: Jid,
    /// `true` = status muted, `false` = unmuted.
    pub muted: bool,
    pub timestamp: DateTime<Utc>,
    pub action: Box<wa::sync_action_value::UserStatusMuteAction>,
    pub from_full_sync: bool,
}

Fields:

jid - The entity whose status updates were (un)muted
muted - true when status was muted, false when unmuted
from_full_sync - true while replaying the initial app state full sync

Example:

Event::UserStatusMuteUpdate(update) => {
    println!("Status of {} {}", update.jid, if update.muted { "muted" } else { "unmuted" });
}

See set_user_status_mute for the outbound API.

DeleteMessageForMeUpdate

Emitted: When a message is deleted locally (not for everyone) across linked devices

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct DeleteMessageForMeUpdate {
    pub chat_jid: Jid,
    pub participant_jid: Option<Jid>,
    pub message_id: String,
    pub from_me: bool,
    pub timestamp: DateTime<Utc>,
    pub action: Box<wa::sync_action_value::DeleteMessageForMeAction>,
    pub from_full_sync: bool,
}

Fields:

chat_jid - The chat containing the deleted message
participant_jid - The sender of the message (only for group messages from others; None for self-authored or 1-on-1 messages)
message_id - The ID of the deleted message
from_me - Whether the deleted message was sent by you
action - The underlying protobuf action containing delete_media and optional message_timestamp

Example:

Event::DeleteMessageForMeUpdate(update) => {
    println!("Message {} in {} deleted for me", update.message_id, update.chat_jid);
}

LabelEditUpdate

Emitted: When a chat label is created, renamed, recolored, or deleted on a linked device

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct LabelEditUpdate {
    pub label_id: String,
    pub timestamp: DateTime<Utc>,
    pub action: Box<wa::sync_action_value::LabelEditAction>,
    pub from_full_sync: bool,
}

Fields:

label_id — Stable label identifier
action.name — New display name (None when only the deleted flag changes)
action.color — WhatsApp color index for the swatch
action.deleted — Some(true) when the label was removed
from_full_sync — true while replaying the initial app state full sync

Example:

Event::LabelEditUpdate(update) => {
    if update.action.deleted == Some(true) {
        println!("Label {} deleted", update.label_id);
    } else {
        println!("Label {} renamed to {:?}", update.label_id, update.action.name);
    }
}

LabelAssociationUpdate

Emitted: When a label is added to or removed from a chat on a linked device

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct LabelAssociationUpdate {
    pub label_id: String,
    pub chat_jid: Jid,
    pub timestamp: DateTime<Utc>,
    pub action: Box<wa::sync_action_value::LabelAssociationAction>,
    pub from_full_sync: bool,
}

Fields:

label_id — Identifier of the label being attached or detached
chat_jid — Chat whose label set changed
action.labeled — Some(true) when the label was added, Some(false) when removed
from_full_sync — true while replaying the initial app state full sync

Example:

Event::LabelAssociationUpdate(update) => {
    let attached = update.action.labeled == Some(true);
    println!(
        "Label {} {} chat {}",
        update.label_id,
        if attached { "added to" } else { "removed from" },
        update.chat_jid,
    );
}

See Labels for the outbound API that emits these events on other devices.

MessageLabelAssociationUpdate

Emitted: When a label is added to or removed from a single message on a linked device

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct MessageLabelAssociationUpdate {
    pub label_id: String,
    pub chat_jid: Jid,
    pub message_id: String,
    pub timestamp: DateTime<Utc>,
    pub action: Box<wa::sync_action_value::LabelAssociationAction>,
    pub from_full_sync: bool,
}

Fields:

label_id — Identifier of the label being attached or detached
chat_jid — Chat containing the labeled message
message_id — Message whose label set changed
timestamp — When the association change occurred
action.labeled — Some(true) when the label was added, Some(false) when removed
from_full_sync — true while replaying the initial app state full sync

Example:

Event::MessageLabelAssociationUpdate(update) => {
    let attached = update.action.labeled == Some(true);
    println!(
        "Label {} {} message {} in chat {}",
        update.label_id,
        if attached { "added to" } else { "removed from" },
        update.message_id,
        update.chat_jid,
    );
}

Distinct from LabelAssociationUpdate above — that event is a whole-chat association, this one is scoped to a single message. See Labels — Associate a label with a message for the outbound API.

QuickReplyUpdate

Emitted: When a quick reply is created, edited, or deleted on a linked device

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct QuickReplyUpdate {
    pub id: String,
    pub timestamp: DateTime<Utc>,
    pub action: Box<wa::sync_action_value::QuickReplyAction>,
    pub from_full_sync: bool,
}

Fields:

id — Stable quick reply identifier
timestamp — When the change occurred
action.shortcut — The /-typed trigger text
action.message — The expanded message text
action.deleted — Some(true) when the quick reply was deleted
from_full_sync — true while replaying the initial app state full sync

Example:

Event::QuickReplyUpdate(update) => {
    if update.action.deleted == Some(true) {
        println!("Quick reply {} deleted", update.id);
    } else {
        println!("Quick reply {} = {:?}", update.id, update.action.shortcut);
    }
}

Deletion is the same mutation with action.deleted == Some(true), not a syncd Remove — check that flag rather than assume the event always describes a live quick reply. See Quick Replies for the outbound API that emits this event on other devices.

History sync events

HistorySync

Emitted: For chat history synchronization

Event::HistorySync(Box<LazyHistorySync>)

LazyHistorySync holds the original compressed zlib payload and only decodes the full wa::HistorySync proto on demand. Cheap metadata (sync_type, chunk_order, progress) is available without decoding. Queued events are ~10× smaller than the decompressed form — a typical InitialBootstrap chunk is 5–20 MB inflated, ~1–2 MB compressed.

pub struct LazyHistorySync {
    compressed: Bytes,         // original zlib payload (reference-counted)
    decompressed_size: usize,  // exact inflated byte count
    sync_type: i32,
    chunk_order: Option<u32>,
    progress: Option<u32>,
    peer_data_request_session_id: Option<String>,
    parsed: OnceLock<Option<Box<wa::HistorySync>>>,
}

impl LazyHistorySync {
    /// History sync type (e.g. InitialBootstrap, Recent, PushName).
    /// Available without decoding the proto.
    pub fn sync_type(&self) -> i32;

    /// Chunk ordering for multi-chunk transfers.
    pub fn chunk_order(&self) -> Option<u32>;

    /// Sync progress (0-100).
    pub fn progress(&self) -> Option<u32>;

    /// Session ID set only on ON_DEMAND syncs. Use it to correlate the
    /// blob with the original `fetchMessageHistory` /
    /// `requestPlaceholderResend` request. Server-pushed syncs return
    /// `None`.
    pub fn peer_data_request_session_id(&self) -> Option<&str>;

    /// Exact inflated byte count (known without decompressing).
    pub fn decompressed_size(&self) -> usize;

    /// The stored compressed bytes (reference-counted, zero-copy).
    pub fn compressed_bytes(&self) -> &Bytes;

    /// Inflate the payload into a fresh buffer on each call (no caching).
    /// Use `get()` for repeated full-proto access.
    pub fn decompress(&self) -> std::io::Result<Bytes>;

    /// Streaming reader: yields one conversation at a time with bounded
    /// peak memory. See the `HistorySyncStream` section below.
    pub fn stream(&self) -> HistorySyncStream<'_>;

    /// Full decode of the history sync proto, cached via OnceLock.
    /// Returns `None` if decoding fails. The compressed payload stays
    /// accessible after this call — `compressed_bytes()`, `decompress()`,
    /// and `stream()` all keep working.
    pub fn get(&self) -> Option<&wa::HistorySync>;
}

Key characteristics:

Metadata without decoding — sync_type(), chunk_order(), progress(), and peer_data_request_session_id() are extracted during the streaming phase and available immediately
Parse-once semantics — get() decodes the full proto on first call and caches the result via OnceLock. With Arc<Event> dispatch, all handlers share the same LazyHistorySync instance. The compressed payload is never consumed — get() can be called multiple times and other accessors still work afterward
Cheap clone — Clone is a refcount bump on the compressed buffer; no decode cache is carried over, so each cloned instance re-inflates independently on demand
Decompress on demand — decompress() re-inflates into a fresh buffer on every call (no caching). Use get() for repeated full-proto access, or stream() for memory-bounded incremental access
Streaming — stream() yields one conversation at a time via HistorySyncStream, keeping peak memory near the largest single conversation rather than the full decompressed size
Serialization — Only metadata (sync_type, chunk_order, progress, peer_data_request_session_id) is serialized, not the blob
On-demand correlation — peer_data_request_session_id() is set only on syncs the server pushes in response to fetchMessageHistory / requestPlaceholderResend. Server-initiated syncs (initial bootstrap, recent, push-name) return None. Use it to route the blob back to the request that triggered it.

For large InitialBootstrap blobs, prefer stream() for incremental processing or decompress() for one-shot custom decoding. When decompressed_size() is large (e.g. > 256 KB), wrap the call in tokio::task::spawn_blocking (cloning compressed_bytes() into the closure) to avoid blocking the async runtime.

Example — full decode:

Event::HistorySync(lazy_sync) => {
    println!("History sync type: {}, progress: {:?}",
        lazy_sync.sync_type(), lazy_sync.progress());

    // Full decode (cached after first call)
    if let Some(history) = lazy_sync.get() {
        for conv in &history.conversations {
            println!("Conversation: {:?}", conv.id);
        }
    }
}

Example — streaming (memory-bounded):

Event::HistorySync(lazy_sync) => {
    let mut stream = lazy_sync.stream();

    while let Some(conv) = stream.next_conversation()? {
        println!("Conversation: {:?}", conv.id);
    }

    // Decode everything that is not a conversation (pushnames, mappings, …)
    let remainder = stream.remainder()?;
    println!("Pushnames: {}", remainder.pushnames.len());
}

Example — decompress for custom parsing:

Event::HistorySync(lazy_sync) => {
    let bytes = lazy_sync.decompress()?;
    let history = wa::HistorySync::decode(bytes.as_ref())?;
}

The blob is only retained in memory if event handlers are registered. If no handlers are listening, the history sync pipeline extracts internal data (pushname, NCT salt, TC tokens) and discards the blob without allocating it for event dispatch.

HistorySyncStream

wacore::history_sync::HistorySyncStream iterates a compressed blob with bounded memory. At any point, only the current inflate window plus the largest single serialized conversation is resident — the full decompressed blob is never materialized.

pub struct HistorySyncStream<'a> { /* … */ }

impl<'a> HistorySyncStream<'a> {
    /// Wrap a compressed blob with a decompressed-size cap.
    /// Use `MAX_DECOMPRESSED` (64 MB) as the default cap, or
    /// `LazyHistorySync::decompressed_size()` for an exact-size bound.
    pub fn new(compressed: &'a [u8], max_decompressed: u64) -> Self;

    /// Advance to the next conversation, returning its raw bytes.
    /// Returns `Ok(None)` when all conversations are exhausted.
    pub fn next_conversation_bytes(&mut self) -> Result<Option<&[u8]>, HistorySyncError>;

    /// Advance to the next conversation, decoding it via buffa.
    /// Corrupt entries are skipped and counted via `skipped_conversations()`.
    /// Allocates a fresh `Conversation` per call — a drain loop over
    /// thousands of entries should prefer `next_conversation_into`.
    pub fn next_conversation(&mut self) -> Result<Option<wa::Conversation>, HistorySyncError>;

    /// In-place variant of `next_conversation`: decodes into `conversation`,
    /// returning `Ok(false)` at clean EOF. buffa's `clear()` retains `Vec`
    /// capacity, so reusing one struct across a drain loop skips the
    /// per-conversation message-spine reallocations. Corrupt entries are
    /// skipped and counted via `skipped_conversations()`, matching the
    /// behaviour of `next_conversation`. After `Ok(false)` (or an error)
    /// the struct's contents are unspecified.
    pub fn next_conversation_into(&mut self, conversation: &mut wa::Conversation) -> Result<bool, HistorySyncError>;

    /// Number of conversations skipped due to decode errors.
    pub fn skipped_conversations(&self) -> usize;

    /// Decode all non-conversation fields (pushnames, mappings, nctSalt, …)
    /// regardless of wire order.
    ///
    /// Must be called after exhausting conversations. Calling it early
    /// (while unread conversations remain) returns
    /// `Err(HistorySyncError::UnreadConversations)`.
    pub fn remainder(self) -> Result<wa::HistorySync, HistorySyncError>;
}

/// Default decompressed-size cap for `HistorySyncStream::new`.
pub const MAX_DECOMPRESSED: u64 = 64 * 1024 * 1024;

Error variants relevant to streaming:

Variant	When
`HistorySyncError::UnreadConversations`	`remainder()` called before conversations were exhausted
Other I/O variants	Truncated zlib stream, malformed length-delimited field

OfflineSyncPreview

Emitted: Preview of pending offline sync data when reconnecting

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct OfflineSyncPreview {
    pub total: i32,
    pub app_data_changes: i32,
    pub messages: i32,
    pub notifications: i32,
    pub receipts: i32,
    pub calls: i32,
    pub statuses: i32,
}

total is authoritative — the <ib><offline_preview> stanza’s own count attribute — and the per-kind counts are not guaranteed to sum to it. calls and statuses count the server’s call and status backlog attributes; a server that predates these fields leaves both at 0. Example:

Event::OfflineSyncPreview(preview) => {
    println!("Syncing {} items ({} messages, {} statuses, {} notifications)", 
        preview.total, preview.messages, preview.statuses, preview.notifications);
}

OfflineSyncCompleted

Emitted: When offline sync completes after reconnection

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct OfflineSyncCompleted {
    pub count: i32,
}

Example:

Event::OfflineSyncCompleted(sync) => {
    println!("Offline sync completed: {} items processed", sync.count);
}

OfflineSyncInterrupted

Emitted: When an offline backlog drain ends because its connection was lost, before the <ib><offline/> end marker arrived (added in PR #1380)

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct OfflineSyncInterrupted {
    pub total: i32,
    pub delivered: i32,
}

total is what the preceding OfflineSyncPreview announced for this drain; delivered is how many offline stanzas were processed before the connection ended. The server owns both numbers, so treat the pair as a progress report rather than an invariant — delivered is never larger than total in practice, but that isn’t guaranteed. This is the counterpart to OfflineSyncCompleted, not a variant of it: the drain did not finish, the client is not caught up, and the rest of the backlog is still queued server-side. delivered counts stanzas processed, not stanzas guaranteed never to come back — what the next connection’s OfflineSyncPreview actually redelivers follows the pre-existing commit-batch ack contract, unchanged by this event: see Inbound Durability → Batching for exactly which batch a mid-drain disconnect does and doesn’t redeliver. A consumer that gates “caught up” UI or startup work on OfflineSyncCompleted should treat this event as “not caught up yet, wait for the next preview” rather than as completion. Exactly one of OfflineSyncCompleted / OfflineSyncInterrupted is emitted per resume — never both, and never neither. Example:

Event::OfflineSyncInterrupted(e) => {
    println!("Offline resume interrupted: {} of {} items delivered before disconnect", e.delivered, e.total);
}

Offline sync happens automatically when the client reconnects after being disconnected. The client tracks progress internally and emits these events to notify your application of sync status.If the server stops sending offline stanzas before the end marker arrives, but the connection itself stays up, an inactivity watchdog completes the drain — mirroring WhatsApp Web’s own stall timer — and OfflineSyncCompleted still fires, with the count of items processed so far. The watchdog re-arms on every stanza, so it fires somewhere between 60 and 120 seconds after the last one rather than at a fixed 60 seconds.If instead the connection ends before the drain finishes, the resume is never left silent: it is reported as OfflineSyncInterrupted rather than OfflineSyncCompleted (added in PR #1380). This event only reports that the resume ended abnormally — what the next connection’s OfflineSyncPreview actually redelivers still follows the pre-existing commit-batch ack contract; see Inbound Durability → Batching.

DirtyState

Emitted: When the server sends an <ib><dirty type="..." timestamp="..."> marker, telling the client one of its cached protocol domains is stale server-side.

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct DirtyState {
    pub dirty_type: DirtyType,
    pub timestamp: Option<u64>,
}

Fields:

dirty_type - The stale domain, mirroring wacore::iq::dirty::DirtyType: AccountSync, Groups, SyncdAppState, NewsletterMetadata, or Other(String) for a wire value the client doesn’t otherwise recognize.
timestamp - Option<u64>, None if the <dirty> stanza omitted the timestamp attribute.

This is a pure observability hook — it does not replace or gate the client’s built-in handling. The client always sends the matching <clean> IQ (throttled behind offline-sync completion for Groups/NewsletterMetadata, per WAWebHandleDirtyBits) and, for SyncdAppState, re-syncs all app-state collections, exactly as it did before this event existed. DirtyState fires first, right before that built-in work starts, so a handler can refresh its own domain-specific derived state (e.g. invalidate a local groups cache) without parsing raw <ib> stanzas via RawNode or racing the client’s own resync.

Example:

use wacore::iq::dirty::DirtyType;

Event::DirtyState(DirtyState { dirty_type, timestamp, .. }) => {
    match dirty_type {
        DirtyType::Groups => println!("groups cache is stale (as of {timestamp:?})"),
        DirtyType::SyncdAppState => println!("app-state re-sync incoming"),
        other => println!("dirty: {other:?} at {timestamp:?}"),
    }
}

AppStateSyncFailed

Emitted: When a batched app-state sync (fetching syncd collections like critical_block, regular_high) finishes without leaving every requested collection synced.

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct AppStateSyncFailed {
    pub fatal: Vec<String>,
    pub retryable: Vec<String>,
    pub skipped: Vec<String>,
    pub connected: bool,
}

Fields:

fatal - Collections the server refused outright (the syncd IQ came back with an IQ-level error code such as 400/404, not an HTTP status). Terminal for the current connection — repeating the request on it gets the same answer — but not permanent: a fresh connection gets to try again.
retryable - Collections that didn’t sync but a later attempt can. The client retries these itself, backing off from 1 second and doubling (a theoretical one-hour cap that its round limit never lets it reach), for up to APP_STATE_RETRY_MAX_ROUNDS (8) rounds — about four minutes — before giving up and reporting one more AppStateSyncFailed for whatever is still unsynced. A handler doesn’t need to trigger a retry itself.
skipped - Collections another in-flight sync or patch send already held, so this particular sync did nothing for them. Not an error, and not itself re-queued into the retry schedule above — the equivalent work is happening elsewhere and will report its own outcome.
connected - Whether the client was already connected (or went on to dispatch Event::Connected) when this event fired, rather than an indicator of which bucket is non-empty. As of PR #1291, during the initial bootstrap it’s true for every outcome that reaches an answer — synced-with-gaps, fatal, retryable, or skipped, including a batch that failed transport-side before producing any per-collection buckets. It’s false when the client was paused, asked to disconnect, or the server rejected the session (429/503), between the sync finishing and the announcement: Connected is withheld but this event still fires, and the leftover collections still go to the background sync either way. If the connection’s generation was retired instead — a replacement connection already took over — neither event fires for this one at all; the replacement reports for itself once its own sync finishes. Outside the bootstrap, background syncs always run on an already-connected client, so connected is true there regardless of which buckets are populated.

Collections are identified by their wire name (critical_block, critical_unblock_low, regular_high, regular_low, regular) rather than an enum, so this payload stays stable if the set of collections changes.fatal is the bucket a consumer usually has to act on. WhatsApp Web treats a fatal critical_block failure as grounds to notify the primary device and log out; this library does not end a session on its own. Instead, during the initial connection bootstrap, a fatal critical_block outcome makes the client stop waiting on it, dispatch Event::Connected anyway, and then dispatch this event with connected: true — the account is usable but missing whatever that collection carries. A fatal outcome does not retry on its own connection (WhatsApp Web’s COMPANION_SYNCD_SNAPSHOT_FATAL_RECOVERY path is explicitly gated off for critical_block, and this client implements no alternative for it); the collection gets another chance only on the account’s next fresh connection. critical_block includes the setting_pushName mutation, so unless the push name was already known some other way (e.g. Bot::with_push_name, or a name learned earlier via history sync or a prior session), presence stays unavailable until that next connection syncs it. See Critical app-state sync (pairing bootstrap) for the full bootstrap flow.As of PR #1291, a retryable or skipped outcome during the bootstrap is no longer silent either: the client dispatches Connected and this event (connected: true) the same way it does for fatal, then hands the leftovers to the background sync that follows. Both buckets get one more attempt as part of that sync’s own batched request; whatever is still retryable after that enters the bounded backoff described above, and a skipped collection is handled the same way the skipped field description above does outside the bootstrap too. A handler that only reacted to fatal before should now also watch retryable/skipped if it needs to know the account is running in a degraded state, since both can now arrive alongside a Connected that announced a session missing its push name or blocklist.A background sync outside the bootstrap path (the ib dirty-resync handler, group server_sync notifications, periodic app-state resync) reports through this same event when it leaves collections unsynced, always with connected: true since the client was already connected before that sync ran. Only its retryable collections back off and retry automatically; any fatal collection it reports is subject to the same next-connection-only recovery as the bootstrap path.

Example:

Event::AppStateSyncFailed(AppStateSyncFailed { fatal, retryable, connected, .. }) => {
    if !fatal.is_empty() {
        eprintln!("app-state collections unsynced on this connection: {fatal:?}");
    }
    if !retryable.is_empty() {
        println!("app-state collections retrying in background: {retryable:?}");
    }
    if connected {
        println!("connected anyway, degraded until the above resolves");
    }
}

ClientExpirationChanged

Emitted: When the server sends (or withdraws) an <ib><client_expiration t="..."> marker — the date it expects to stop accepting the client build currently running. Fires only when the stored expires_at resolves to a different value than what was already held; a t the server resends that resolves to the same stored deadline is silent, so a handler wired to alert on this event doesn’t fire on every reconnect just because the server repeats itself. That’s not the same as “the same t is always silent” — see the note below.

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct ClientExpirationChanged {
    pub expires_at: Option<i64>,
    pub version: (u32, u32, u32),
    pub withdrawn: bool,
}

Fields:

expires_at - Unix seconds after which the server expects to stop accepting this build. None when the deadline was withdrawn (withdrawn: true).
version - The (primary, secondary, tertiary) build the deadline was issued against — a deadline issued for one build says nothing about the next, so this is how a consumer checks the announcement still applies to the running binary.
withdrawn - true when the server retracted a deadline it had previously set (the <client_expiration> child arrived with no t attribute).

This is notice, not an instruction. The client keeps connecting until the server actually refuses it — the stanza is about the build, not the current connection — so whether to ship a newer version or alert an operator is the consumer’s call; this library never disconnects on its own because of it.The recorded deadline is never sooner than three days out, even when the server’s own answer is more abrupt (t at or before now) — a server that says “now” still has to leave a window in which the build can be replaced. The raw t is only acted on when it’s sooner than the expires_at already stored — a t at or after that is treated as a stale retransmit or a host that hasn’t caught up, and is ignored rather than granted as an extension. That gate gets re-evaluated against “now” each time, though, so it does not mean the stored deadline can only move earlier over time: a server that keeps resending the same already-elapsed t keeps clearing the gate (it stays “sooner than stored”) and each acceptance re-floors three days out from the new “now” — pushing the stored deadline later each time even though t itself never changed. A dated deadline in the future, by contrast, settles once stored: restating it no longer clears the gate, so repeats change nothing and dispatch nothing. See ServerClientExpiration for the persisted record and the full decision rule.

Example:

Event::ClientExpirationChanged(ClientExpirationChanged { expires_at, version, withdrawn, .. }) => {
    if withdrawn {
        println!("client expiration deadline withdrawn for build {version:?}");
    } else if let Some(expires_at) = expires_at {
        println!("build {version:?} will stop being accepted at {expires_at}");
    }
}

Device Events

DeviceListUpdate

Emitted: When a user’s device list changes (a companion device is added, removed, or updated)

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct DeviceListUpdate {
    pub user: Jid,
    pub lid_user: Option<Jid>,
    pub update_type: DeviceListUpdateType,
    pub devices: Vec<DeviceNotificationInfo>,
    pub key_index: Option<KeyIndexInfo>,
    pub contact_hash: Option<String>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub enum DeviceListUpdateType {
    Add,
    Remove,
    Update,
}

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct DeviceNotificationInfo {
    pub device_id: u32,
    pub key_index: Option<u32>,
}

Fields:

Field	Description
`user`	The user whose device list changed (PN JID)
`lid_user`	The user’s LID JID, if known from the notification
`update_type`	Whether a device was added, removed, or updated
`devices`	List of affected devices with their IDs and key indexes
`key_index`	ADV key index info for device identity verification (add operations only)
`contact_hash`	Server-side contact hash for update operations

This event is dispatched after the client has already patched its internal device registry cache. You can use it to track when contacts pair or unpair companion devices. The client also uses device list changes internally to manage unknown device detection, Signal session cleanup, and sender key cache invalidation — when a device is added or removed, the sender key device cache is invalidated so SKDM is redistributed on the next group message.

IdentityChange

Emitted: When a contact reinstalls WhatsApp (their identity key changed). The event fires from two paths: an explicit server <identity/> notification, or a locally-detected change discovered while decrypting an incoming message. The implicit field distinguishes them.

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct IdentityChange {
    /// The user whose identity changed
    pub user: Jid,
    /// Optional LID for the user
    pub lid_user: Option<Jid>,
    /// `true` when detected locally during decrypt (mirrors WA Web
    /// `saveIdentity` -> `handleNewIdentity`), `false` when triggered by the
    /// server's `<identity/>` notification.
    pub implicit: bool,
}

Fields:

user — The phone number JID of the user whose identity changed
lid_user — The user’s LID JID, if provided in the notification
implicit — false for server-pushed <identity/> notifications (full cleanup performed); true for locally-detected changes during decrypt (lighter cleanup, see below)

This event corresponds to WhatsApp Web’s WAWebHandleIdentityChange flow. When the server sends an <identity/> notification inside a type="encrypt" stanza, the client:

Clears the device record for the user (deletes Signal sessions for all non-primary devices). Per-device sender key tracking is not wiped here — matching WhatsApp Web’s WAWebUpdateLocalSignalSession, SKDM redistribution is driven per-group/per-device by retry receipts (markForgetSenderKey), so a global wipe would empty the tracker too aggressively.
Deletes the primary device session and identity key so a fresh session can be established (matching WhatsApp Web’s deleteRemoteInfo)
Deletes the status@broadcast sender key for forward secrecy on the next status send (matching WhatsApp Web’s markStatusSenderKeyRotate)
Invalidates the device registry cache so the next send triggers a fresh device list sync
Dispatches this event so your application can show a “security code changed” notice
Spawns a background ensure_e2e_sessions task to proactively re-establish the session (self-defers when the client is offline)

Additionally, when a message triggers an UntrustedIdentity error during decryption (indicating the sender reinstalled WhatsApp), the client:

Clears the old identity key and retries decryption with the new identity, preserving the old session for in-flight messages
Handles InvalidPreKeyId errors in the retry path by sending a retry receipt so the sender can establish a new session
Re-issues TC tokens for the sender in the background (matching WhatsApp Web’s sendTcTokenWhenDeviceIdentityChange behavior) so the contact retains a valid privacy token

The notification is processed immediately even when received during offline sync, because all cleanup operations are local-only. The background session re-establishment self-defers via wait_for_offline_delivery_end when the client is offline.

Implicit (locally-detected) identity changes

The client also fires IdentityChange with implicit: true when decrypting a peer’s message replaces an existing identity key with a different one — for example, when a contact’s reinstall reaches you through an incoming message before the server <identity/> push arrives. This mirrors WhatsApp Web’s saveIdentity → handleNewIdentity flow. The implicit path is deliberately lighter than the server push:

Clears the device record (non-primary sessions + per-device sender key tracking)
Invalidates the device registry cache so the next send re-runs usync
Re-issues an active TC token if one exists

It does not delete the primary session, rotate the status@broadcast sender key, or proactively re-establish sessions — the in-flight message is already establishing a new session, and the heavier reset is handled when the server <identity/> push reliably follows.

Identity change notifications from companion devices (device ID != 0) and from your own JID are ignored on both paths — only primary device identity changes for other users are processed.

Example:

Event::IdentityChange(change) => {
    if change.implicit {
        // Detected while decrypting an incoming message — the server
        // <identity/> push will usually follow with the full reset.
        println!("Local identity change for {}", change.user);
    } else {
        println!("Security code changed for user {}", change.user);
    }
    if let Some(lid) = &change.lid_user {
        println!("LID: {}", lid);
    }
    // Show a "security code changed" notice in the chat
}

BusinessStatusUpdate

Emitted: When a business account status changes

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct BusinessStatusUpdate {
    pub jid: Jid,
    pub update_type: BusinessUpdateType,
    pub timestamp: DateTime<Utc>,
    pub target_jid: Option<Jid>,
    pub hash: Option<String>,
    pub verified_name: Option<String>,
    pub product_ids: Vec<String>,
    pub collection_ids: Vec<String>,
    pub subscriptions: Vec<BusinessSubscription>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub enum BusinessUpdateType {
    RemovedAsBusiness,
    VerifiedNameChanged,
    ProfileUpdated,
    ProductsUpdated,
    CollectionsUpdated,
    SubscriptionsUpdated,
    Unknown,
}

NewsletterLiveUpdate

Emitted: When reaction counts change or messages are updated on a newsletter you’re subscribed to (via subscribe_live_updates).

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct NewsletterLiveUpdate {
    pub newsletter_jid: Jid,
    pub messages: Vec<NewsletterLiveUpdateMessage>,
}

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct NewsletterLiveUpdateMessage {
    pub server_id: u64,
    pub reactions: Vec<NewsletterLiveUpdateReaction>,
}

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct NewsletterLiveUpdateReaction {
    pub code: String,
    pub count: u64,
}

Fields:

newsletter_jid — The newsletter channel this update is for
messages — List of messages with updated reaction counts
server_id — Server-assigned message ID
reactions — Current reaction counts (emoji code and count)

Example:

Event::NewsletterLiveUpdate(update) => {
    println!("Newsletter {} updated:", update.newsletter_jid);
    for msg in &update.messages {
        for r in &msg.reactions {
            println!("  Message {}: {} x{}", msg.server_id, r.code, r.count);
        }
    }
}

You must call client.newsletter().subscribe_live_updates(&jid) to receive these events. The subscription has a limited duration (typically 300 seconds) and must be renewed periodically.

Call Events

IncomingCall

Emitted: When the server delivers a <call> stanza — voice or video, 1-on-1 or group. Mirrors WhatsApp Web’s inbound call signaling.

#[derive(Debug, Clone, Serialize)]
pub struct IncomingCall {
    pub from: Jid,
    /// Stanza id; distinct from `CallAction::call_id`.
    pub stanza_id: String,
    pub notify: Option<String>,
    pub platform: Option<String>,
    pub version: Option<String>,
    #[serde(with = "chrono::serde::ts_seconds")]
    pub timestamp: DateTime<Utc>,
    pub offline: bool,
    pub action: CallAction,
    /// The rotation the sending device announced on this stanza's `<video>` child, in
    /// `0..=3`. Only an `<offer>` and an `<accept>` carry one — `None` everywhere else,
    /// and for a stanza whose value was out of range.
    pub video_orientation: Option<u8>,
    /// Group snapshot embedded in an initial offer or active-call invitation. `Some` only for
    /// group calls — see the VoIP guide's [Group calls](/guides/voip-calls#group-calls) section.
    pub group: Option<Box<GroupCallUpdate>>,
}

group_jid: Some(...) on CallAction::Offer (below) is what distinguishes a group call offer from a 1:1 one; group on IncomingCall carries its roster snapshot. See Group calls and Call links in the VoIP guide for accepting one and attaching media.

PR #1402 changed the Event::IncomingCall variant to hold Box<IncomingCall> instead of IncomingCall by value. At 432 bytes it was one of the two variants sizing every dispatched Event, and the per-dispatch Arc<Event> allocation is now 200 bytes smaller (size_of::<Event>() dropped from 528 to 328). Field reads and &call coercions, as in the examples on this page, are unchanged. A pattern that destructures IncomingCall { .. } directly inside the variant must bind the box first or deref it with &*.

PR #1355 added video_orientation. IncomingCall only fires for a stanza the peer sent, so this field is always their rotation, never your own. As a callee, it’s the caller’s rotation, carried on the Offer. As a caller, it’s the callee’s rotation, carried on the Accept you receive back. A video-from-start party announces its camera rotation exactly once, in that stanza, and sends no mid-call <video> of its own until the camera actually turns. Before this field existed, that initial rotation was dropped: a call starting with the peer’s phone already sideways rendered upright until their next rotation change. See Video I/O in the VoIP guide for how this compares to VideoFrame::orientation.

GroupCallUpdate is the same authoritative roster/relay type CallHandle::group_state() exposes once you’ve joined (via GroupCallState::snapshot() — see Reading group state):

pub struct GroupCallUpdate {
    pub call_id: String,
    pub call_creator: Jid,
    pub group_jid: Option<Jid>,
    pub transaction_id: u32,
    pub media: String,
    pub connected_limit: u32,
    pub joinable: bool,
    pub av_upgradable: bool,
    pub rekey_requested: bool,
    pub participants: Vec<GroupCallParticipant>,
    pub relay: Option<GroupCallRelay>,
}

pub struct GroupCallParticipant {
    pub jid: Jid,
    pub state: Option<String>,          // "connected", …
    pub participant_type: Option<String>,
    pub devices: Vec<GroupCallDevice>,  // jid, platform, pid, capability_version
}

The action field is a tagged enum that mirrors the inner stanza child (<offer>, <offer_notice>, <preaccept>, <accept>, <reject>, <terminate>):

#[derive(Debug, Clone, Serialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum CallAction {
    Offer {
        call_id: String,
        call_creator: Jid,
        caller_pn: Option<Jid>,
        caller_country_code: Option<String>,
        device_class: Option<String>,
        joinable: bool,
        is_video: bool,
        audio: Vec<CallAudioCodec>,
        /// Set on group calls. Primary group signal per `WAWebVoipGatingUtils`.
        group_jid: Option<Jid>,
    },
    /// Group-call notification fan-out to members. The router acks it via the
    /// generic call ack — no offer-receipt is expected.
    OfferNotice {
        call_id: String,
        call_creator: Jid,
        is_video: bool,
        is_group: bool,
    },
    PreAccept { call_id: String, call_creator: Jid },
    Accept    { call_id: String, call_creator: Jid },
    Reject    { call_id: String, call_creator: Jid },
    Terminate {
        call_id: String,
        call_creator: Jid,
        duration: Option<u32>,
        audio_duration: Option<u32>,
    },
}

Behavior:

The router automatically acks every <call> stanza. For Offer it additionally sends an <receipt><offer/></receipt> so the caller’s UI advances past “ringing”.
OfferNotice is the server’s fan-out to other group members when a group call starts. No offer-receipt is sent — only the generic ack.
Use action.call_id() and action.call_creator() to access the common identifiers without matching every variant.

Detecting group calls:

Event::IncomingCall(call) => match &call.action {
    CallAction::Offer { is_video, group_jid: Some(group), .. } => {
        // 1-to-many group call offer addressed directly to you.
        let kind = if *is_video { "video" } else { "voice" };
        println!("Incoming group {kind} call in {group} from {}", call.from);
    }
    CallAction::Offer { is_video, group_jid: None, .. } => {
        let kind = if *is_video { "video" } else { "voice" };
        println!("Incoming 1-on-1 {kind} call from {}", call.from);
    }
    CallAction::OfferNotice { is_group: true, is_video, call_creator, .. } => {
        // Group-call fan-out: another member started a call in a group you belong to.
        let kind = if *is_video { "video" } else { "voice" };
        println!("Group {kind} call started by {call_creator}");
    }
    CallAction::Terminate { call_id, duration, .. } => {
        println!("Call {call_id} ended after {:?}s", duration);
    }
    _ => {}
},

group_jid on CallAction::Offer is the primary signal for distinguishing a group call from a 1-on-1 call (matches WhatsApp Web’s WAWebVoipGatingUtils). OfferNotice is the secondary signal for members who were not directly offered the call — for example, when you are a passive group member receiving the announcement that a call started.

Notification Events

DisappearingModeChanged

Emitted: When a contact changes their default disappearing messages setting, sent by the server as a <notification type="disappearing_mode"> stanza — or when your own account’s default changes on another linked device, carried instead as a <disappearing_mode duration="…" t="…"> child of a <notification type="account_sync"> stanza. In the account_sync case from is your own account.

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct DisappearingModeChanged {
    pub from: Jid,
    pub duration: u32,
    #[serde(with = "chrono::serde::ts_seconds")]
    pub setting_timestamp: DateTime<Utc>,
}

Fields:

from - Whose disappearing messages setting changed: a contact for the disappearing_mode notification, or your own account for the account_sync form
duration - New duration in seconds (0 = disabled, 86400 = 24 hours, 604800 = 7 days, etc.)
setting_timestamp - DateTime<Utc> indicating when the setting was changed (serialized as Unix timestamp in seconds)

You should only apply this update if setting_timestamp is newer than your previously stored value for from. This prevents out-of-order updates from overwriting newer settings.

The account_sync form of this notification has a second shape the library does not turn into this event: a <disappearing_mode action="modify"> child (no duration/t) means the server wants you to re-query the current default rather than stating it inline. Resolving that requires a disappearing_mode get request, which this library does not yet implement, so that shape is logged and no event fires.

Example:

Event::DisappearingModeChanged(change) => {
    let status = if change.duration == 0 {
        "disabled".to_string()
    } else {
        format!("enabled ({}s)", change.duration)
    };
    println!("{} changed disappearing messages: {}", change.from, status);
}

Privacy events

DisableLinkPreviewsUpdate

Emitted: When the account-wide “disable link previews” setting changes via app-state sync on a linked device (setting_disableLinkPreviews)

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct DisableLinkPreviewsUpdate {
    pub previews_disabled: bool,
    pub timestamp: DateTime<Utc>,
    pub action: Box<wa::sync_action_value::PrivacySettingDisableLinkPreviewsAction>,
    pub from_full_sync: bool,
}

Fields:

previews_disabled - true when link previews are now disabled. This event only fires when the wire carried the flag. WhatsApp Web treats a mutation with an absent flag as malformed, so no event fires for that case, rather than one carrying a default false.
timestamp - When the change occurred
action - The underlying app-state action
from_full_sync - Whether this came from a full app-state sync (initial load) or an incremental update

Example:

Event::DisableLinkPreviewsUpdate(update) => {
    println!("Link previews disabled: {}", update.previews_disabled);
}

DisappearingModeChanged above is a server-push notification — usually about another contact’s setting (type="disappearing_mode"), though its account_sync shape carries your own account’s setting instead. DisableLinkPreviewsUpdate is different: it is app-state sync about your own account’s setting, changed from one of your own linked devices. See Privacy — App-state settings for the outbound API (set_link_previews_disabled) that emits this event on other devices.

Raw stanza events

`RawNode`

Emitted: The raw stanza received from the server. To receive this event, call client.set_raw_node_forwarding(true) to enable dispatch and include EventKind::RawNode in your handler’s interest(). When forwarding is disabled or no handler wants RawNode, the bus skips this dispatch entirely (zero overhead on the hot path).

Event::RawNode(Arc<OwnedNodeRef>)

This is a library extension with no WhatsApp Web equivalent. It gives you access to every raw decoded stanza before any routing or parsing occurs. The OwnedNodeRef uses yoke-based zero-copy decoding, so string and byte payloads are borrowed directly from the network buffer without allocation. Example:

client.set_raw_node_forwarding(true);

// In your event handler:
Event::RawNode(node) => {
    let node_ref = node.get();
    println!("Raw stanza tag: {}, attrs: {:?}", node_ref.tag, node_ref.attrs);
}

RawNode is skipped during serialization (#[serde(skip)]). Enable it only when debugging or building protocol-level tooling, as it dispatches for every incoming stanza.

Decrypted payload events

`DecryptedPayload`

Emitted: One decrypted <enc> payload, after unpadding and before it is decoded into a wa::Message. To receive this event, hold a lease from client.acquire_decrypted_payload_forwarding() and include EventKind::DecryptedPayload in your handler’s interest(). While no lease is held, nothing is emitted and nothing is cloned.

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct DecryptedPayload {
    pub info: Arc<MessageInfo>,
    pub enc_index: usize,
    pub enc_type: &'static str,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub state: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub session_type: Option<String>,
    #[serde(skip)]
    pub payload: Bytes,
}

Event::DecryptedPayload(DecryptedPayload)

Fields:

info — Which message this came from.
enc_index — Which <enc> of the stanza produced these bytes, counting from zero in the order the client enumerates them: the stanza’s direct <enc> children first, then the ones under <participants><to> addressed to this device (the fan-out shape, where one stanza carries a copy per device and only yours is yours to decrypt). This is a position in that concatenation, not a child index or a position within enc_type’s bucket — an <enc> that produces no payload still consumes its slot, so a consumer correlating a forwarded payload back to its node has to walk the stanza the same way.
enc_type — The type attribute the <enc> carried: msg, pkmsg, skmsg, …
state — The state attribute the <enc> carried, verbatim, or None when it carried none. The server’s own annotation of the session this copy was encrypted under. This build does not model the possible values or act on them; they are handed over as text so a consumer can.
session_type — The session_type attribute the <enc> carried, verbatim, or None when it carried none. Unmodelled and unacted-on, like state.
payload — The plaintext, unpadded, exactly as decoding receives it. A Bytes, so forwarding it is a refcount bump, not a copy.

This is a library extension with no WhatsApp Web equivalent. It exists because a plaintext that decrypts but fails to decode is otherwise lost: handle_decrypted_plaintext turns bytes into wa::Message, and when that decode fails — a field a build predates, a message type it doesn’t model — the bytes disappear. Nothing can ask for them again, because opening them already consumed state that won’t recur: the Signal ratchet advances, so the same ciphertext will never decrypt a second time. DecryptedPayload fires whether or not the decode that follows succeeds, which is the point: the failing case is the one with nothing else to look at. It also enables recording traffic for faithful replay (re-encoding a decoded Message does not reproduce the original bytes) and decoding with a newer protobuf than the running build carries. It’s also emitted on the bot-message-secret path (msg_secret.rs), ahead of the same decode, where the secret a message_secret payload was opened with is single-use rather than ratchet-advanced — the same “cannot be asked for again” property, for a different reason. Example:

let _lease = client.acquire_decrypted_payload_forwarding();

// In your event handler:
Event::DecryptedPayload(payload) => {
    println!(
        "enc #{} ({}) for {}: {} bytes",
        payload.enc_index, payload.enc_type, payload.info.id, payload.payload.len(),
    );
}
// Drop `_lease` to stop forwarding.

payload is skipped during serialization (#[serde(skip)]) — like RawNode, Serialize on an event is for diagnostics, and no text format carries raw bytes without an encoding choice this type has no business making.

See acquire_decrypted_payload_forwarding for the lease API.

Sent frame events

`SentFrame`

Emitted: One marshaled stanza, exactly as it was handed to the noise frame encryption, after the transport accepts the write. To receive this event, hold a lease from client.acquire_sent_frame_forwarding() and include EventKind::SentFrame in your handler’s interest(). While no lease is held, nothing is emitted and nothing is cloned.

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct SentFrame {
    #[serde(skip)]
    pub plaintext: Bytes,
}

Event::SentFrame(SentFrame)

Fields:

plaintext — The marshaled stanza, keeping the leading format byte the binary protocol writes, so decoding it is wacore_binary::marshal::unmarshal_packed_ref(&plaintext). This is the plaintext handed to noise encryption, not a transport frame — the length prefix and the AEAD tag are added after it, and only SessionStats (see WebSocket & Noise Protocol Handling) accounts for those. A Bytes, so forwarding it is a refcount bump, not a copy.

This is the outbound counterpart of RawNode and a library extension with no WhatsApp Web equivalent. Before it existed, the send side had no observer at all: wait_for_sent_node is a filtered one-shot waiter for a single expected stanza, and it only ever sees stanzas that pass through the marshal-and-send path, so the paths that hand pre-marshaled bytes straight to the socket — acks, delivery receipts, direct-encoded IQs — were invisible even to that. SentFrame is emitted from the noise sender task, the single point every send path crosses (including the paths above and the coalesced-burst writes the ack and receipt workers use), so it covers all of them from one place. It exists for recording a session for replay, asserting the wire form in an integration test, and reading back a stanza the server rejected without rebuilding with logging on. Handshake frames are pre-noise and are not covered, and neither are VoIP relay sockets, which — like SessionStats — receive no observers at all. Example:

let _lease = client.acquire_sent_frame_forwarding();

// In your event handler:
Event::SentFrame(frame) => {
    println!("sent {} bytes", frame.plaintext.len());
}
// Drop `_lease` to stop forwarding.

plaintext is skipped during serialization (#[serde(skip)]) — like RawNode and DecryptedPayload, Serialize on an event is for diagnostics, and no text format carries raw bytes without an encoding choice this type has no business making.

See acquire_sent_frame_forwarding for the lease API, and WebSocket & Noise Protocol Handling for how SendObservers wires it into the noise sender.

Enc decrypt failure events

`EncDecryptFailed`

Emitted: One <enc> that did not produce a usable message, and why — the failing half of what DecryptedPayload reports for the succeeding half, at the same granularity (per <enc>, not per message) and under the same numbering (enc_index comes from the same enumeration as DecryptedPayload::enc_index, so the two events index one stanza and not two). To receive this event, hold a lease from client.acquire_enc_decrypt_failed_forwarding() and include EventKind::EncDecryptFailed in your handler’s interest(). While no lease is held, nothing is emitted and nothing is built.

#[derive(Debug, Clone, Serialize, bon::Builder)]
#[non_exhaustive]
pub struct EncDecryptFailed {
    pub info: Arc<MessageInfo>,
    pub enc_index: usize,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub enc_type: Option<Cow<'static, str>>,
    pub reason: EncDecryptFailureReason,
}

Event::EncDecryptFailed(EncDecryptFailed)

Fields:

info — Which message this <enc> belongs to.
enc_index — Which <enc> of the stanza this was, counting from zero in the order the client enumerates them — the stanza’s direct <enc> children first, then the ones under <participants><to> addressed to this device. Not a child index.
enc_type — The type attribute the <enc> carried: msg, pkmsg, skmsg, … None only when the node carried no type attribute at all — the one thing MalformedNode can mean here that a present type does not.
reason — Where the client stopped. See EncDecryptFailureReason below.

This is a library extension with no WhatsApp Web equivalent — WhatsApp’s own client does not surface this. Reasons to want it: attributing a failure inside a fan-out (a stanza can carry one <enc> per device), driving a retry or resync policy off the specific reason, and measuring session health per peer rather than per message.

EncDecryptFailureReason

Why one <enc> produced no plaintext. This is the client’s own classification of where it stopped, not something the server sends and not a statement about the sender’s copy. It is #[non_exhaustive] — a match needs a _ arm, since new branches append new variants as the receive path is refined.

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[non_exhaustive]
pub enum EncDecryptFailureReason {
    MalformedNode,
    UnsupportedEncType,
    MalformedCiphertext,
    NoSession,
    NoSenderKey,
    UnknownPreKey,
    UntrustedIdentity,
    BadMac,
    InvalidMessage,
    NoMessageSecret,
    LocalCryptoFailure,
    SignalError,
    StorageFailure,
    PlaintextUnusable,
    NotAttempted,
}

Variant	Meaning
`MalformedNode`	No `type` attribute, or no content to decrypt — nothing about the node named a decryption to attempt.
`UnsupportedEncType`	Recognized as an `<enc>`, but the `type` is one this build does not implement.
`MalformedCiphertext`	A `type` this build handles, whose body is not a well-formed envelope for it — never reached a cipher. Distinct from `InvalidMessage`, which is the cryptographic layer rejecting an envelope it did parse.
`NoSession`	No Signal session for the sender’s address. Usually recoverable — the client asks the sender to re-establish one.
`NoSenderKey`	No sender-key state for this `(group, sender)` chain — typically an `skmsg` whose distribution message was never received or was lost.
`UnknownPreKey`	The sender encrypted to a one-time or signed pre-key of ours that this device no longer holds.
`UntrustedIdentity`	The sender’s identity key is not the one this device trusts for them. Usually reported after a stored-identity retry still didn’t produce plaintext; also reported where libsignal raises it directly, as with a PN→LID session migration.
`BadMac`	The ciphertext did not verify under the key the client derived for it — covers both the Signal MAC and the AES-GCM tag of a bot (`msmsg`) payload.
`InvalidMessage`	The envelope parsed and the cryptographic layer rejected its contents: a version mismatch, a bad signature, or a body the cipher would not accept under sound keys. Not the same as state that was never sound — that’s `StorageFailure`.
`NoMessageSecret`	A bot (`msmsg`) payload whose `messageSecret` this device does not hold, or whose `<meta>` doesn’t say which secret to look up. Expected on a companion for a group bot invocation the primary device sent.
`LocalCryptoFailure`	The local cryptographic provider failed a key agreement. Ours — like `StorageFailure`, the peer’s ciphertext was never judged.
`SignalError`	The cryptographic layer failed for a reason this build does not classify further.
`StorageFailure`	Local state was the problem, not the ciphertext — a store that wouldn’t answer, a corrupt pre-key/identity/session/sender-key record, or a durability failure. Says nothing about the peer, and nothing about recovery (some branches leave the stanza queued for redelivery, others nack it).
`PlaintextUnusable`	The `<enc>` decrypted, but the bytes couldn’t be turned into a message (padding it couldn’t strip, or an undecodable payload). The one reason that can accompany a `DecryptedPayload` for the same `<enc>` — when the bytes existed but were unusable, both are emitted.
`NotAttempted`	Never attempted: an `skmsg` whose stanza’s session `<enc>` failed first (the sender key it needed came in that one), a session `<enc>` on a stanza addressed from a group, or a stanza abandoned when the connection tore down before its turn. Says nothing about the ciphertext, which was never read.

EncDecryptFailureReason::decryption_was_attempted(self) -> bool reports whether the client entered its decryption path at all — false for MalformedNode, UnsupportedEncType, and NotAttempted; true for every other variant, spanning everything from an envelope that wouldn’t parse to a MAC that wouldn’t verify.

What it does not say

Not a display signal. Whether to show the user a placeholder is UndecryptableMessage, which is per message, deduplicated by (chat, id, sender), and carries the server’s decrypt-fail hint. EncDecryptFailed is per <enc>, is not deduplicated, and answers a different question.
Not a loss report. Most reasons are recoverable — the client may already have asked the sender to resend — and this event says nothing about whether a retry went out or succeeded later.
Repeats. A redelivered stanza that fails again emits it again, once per <enc> per delivery. Correlate on (info.source.chat, info.source.sender, info.id, enc_index) if you want at-most-once per <enc> — info.id alone is not globally unique, only within a (chat, sender) pair (see Idempotency Requirement).
A duplicate is not a failure. An <enc> the server redelivered that this device already processed emits neither this event nor DecryptedPayload — its plaintext was reported the first time round. A stanza whose only duplicate <enc> sits beside one that genuinely fails still reports that other <enc> as NotAttempted, on every delivery, since no delivery ever produced its plaintext.
Order is enc_index, not arrival. The client decrypts a stanza’s <enc> nodes in per-kind passes (session, then group, then bot), so neither these events nor DecryptedPayloads arrive in stanza order, and a failure for a later <enc> can precede a success for an earlier one.

Example:

let _lease = client.acquire_enc_decrypt_failed_forwarding();

// In your event handler:
Event::EncDecryptFailed(failed) => {
    println!(
        "enc #{} ({:?}) for {} failed: {:?}",
        failed.enc_index, failed.enc_type, failed.info.id, failed.reason,
    );
}
// Drop `_lease` to stop forwarding.

See acquire_enc_decrypt_failed_forwarding for the lease API.

Event handler patterns

Bot builder pattern

use whatsapp_rust::bot::Bot;
use wacore::types::events::{Event, InboundMessage};

let mut bot = Bot::builder()
    .with_backend(backend)
    .on_event(|event, client| async move {
        match &*event {
            Event::Messages(batch) => {
                // Handle each message in the batch
                for InboundMessage { message: msg, info, .. } in batch.iter() { /* … */ }
            }
            Event::Connected(_) => {
                // Handle connection
            }
            _ => {}
        }
    })
    .build()
    .await?;

Delivery order and backpressure

Closures registered via on_event, on_event_for, on_message, and the other typed registrars are bridged onto the CoreEventBus by an internal adapter with a configurable delivery strategy, set via BotBuilder::with_event_delivery:

EventDelivery::Concurrent (default) — each event is fanned out to every interested callback on its own spawned task. A slow callback never stalls the bus or its siblings, but ordering across events is not guaranteed, and a persistently slow consumer can accumulate unbounded in-flight tasks.
EventDelivery::Ordered { capacity } — events are handed to a single drainer task through a bounded mailbox and delivered to callbacks strictly in arrival order (within an event, interested callbacks run in registration order). This mirrors the ordered messages.upsert contract of WA Web (preserveOrder: true), whatsmeow, and Baileys. When the mailbox is full the event is dropped — counted in StatsSnapshot::events_dropped — instead of backpressuring the receive pipeline or growing without bound. A panicking callback is caught and logged; the drainer keeps running and later events still get delivered.

Struct-based handlers registered with with_event_handler (or client.register_handler) always run handle_event inline on the dispatch path — EventDelivery only governs the closure-based registrars.

Ordered trades throughput and drop-under-load for a stronger ordering guarantee. If dropped events are unacceptable, pair it with an inbound durability hook for at-least-once redelivery — the hook’s buffering is independent of the delivery mailbox.

Multiple Handlers

struct MessageHandler;
impl EventHandler for MessageHandler {
    fn handle_event(&self, event: Arc<Event>) {
        for InboundMessage { message: msg, info, .. } in event.messages() {
            // Handle messages
        }
    }
}

struct ConnectionHandler;
impl EventHandler for ConnectionHandler {
    fn handle_event(&self, event: Arc<Event>) {
        match &*event {
            Event::Connected(_) => { /* ... */ }
            Event::Disconnected(_) => { /* ... */ }
            _ => {}
        }
    }
}

client.register_handler(Arc::new(MessageHandler));
client.register_handler(Arc::new(ConnectionHandler));

ChannelEventHandler

ChannelEventHandler is a built-in event handler that forwards events to an async_channel for async consumption. It uses async-channel (runtime-agnostic) instead of Tokio channels, so it works with any async executor — including WASM targets. Events are buffered in an unbounded channel, so events fired before the receiver starts listening are not lost.

use wacore::types::events::{ChannelEventHandler, Event, InboundMessage};
use std::sync::Arc;

let (handler, event_rx) = ChannelEventHandler::new();
client.register_handler(handler);

// Wait for events asynchronously
while let Ok(event) = event_rx.recv().await {
    match &*event {
        Event::Connected(_) => {
            println!("Connected!");
            break;
        }
        Event::Messages(batch) => {
            for InboundMessage { info, .. } in batch.iter() {
                println!("Message from {}", info.source.sender);
            }
        }
        _ => {}
    }
}

This is particularly useful for:

Testing — assert on specific event sequences without closures
Custom event loops — process events in your own async task with full control over ordering
Runtime-agnostic code — no dependency on Tokio’s mpsc channels

ChannelEventHandler::new() returns (Arc<ChannelEventHandler>, async_channel::Receiver<Arc<Event>>). The handler is already wrapped in Arc for direct use with client.register_handler(). The receiver yields Arc<Event>, so use &*event or event.as_ref() to pattern-match.

Custom async event handlers

For custom channel-based patterns, you can implement EventHandler directly:

use tokio::sync::mpsc;
use std::sync::Arc;

let (tx, mut rx) = mpsc::unbounded_channel();

struct AsyncHandler {
    tx: mpsc::UnboundedSender<Arc<Event>>,
}

impl EventHandler for AsyncHandler {
    fn handle_event(&self, event: Arc<Event>) {
        let _ = self.tx.send(event);
    }
}

client.register_handler(Arc::new(AsyncHandler { tx }));

// Process events asynchronously
tokio::spawn(async move {
    while let Some(event) = rx.recv().await {
        // event is Arc<Event> — no cloning needed
    }
});

Since events are dispatched as Arc<Event>, you can forward them to channels without any cloning overhead.

Performance Optimization

`LazyHistorySync`

Purpose: Avoid parsing large protobuf blobs unless needed. The compressed payload is stored as reference-counted Bytes, and full protobuf decoding only happens if your code calls get(). See the HistorySync event reference for the complete API.

pub struct LazyHistorySync {
    compressed: Bytes,         // Original zlib payload (reference-counted, ~10× smaller than decompressed)
    decompressed_size: usize,  // Exact inflated byte count
    sync_type: i32,            // Cheap metadata
    chunk_order: Option<u32>,
    progress: Option<u32>,
    peer_data_request_session_id: Option<String>,   // Set only on ON_DEMAND syncs
    parsed: OnceLock<Option<Box<wa::HistorySync>>>, // Decoded on first access
}

Cloning: Clone is a refcount bump on the compressed buffer. No decode cache is carried over — each clone re-inflates independently on demand. Usage:

Event::HistorySync(lazy_sync) => {
    // Metadata is always available without decoding
    let sync_type = lazy_sync.sync_type();
    let progress = lazy_sync.progress();

    // Full decode (cached after first call)
    if let Some(history) = lazy_sync.get() {
        for conv in &history.conversations {
            process_conversation(conv);
        }
    }

    // Streaming: memory-bounded, one conversation at a time
    let mut stream = lazy_sync.stream();
    while let Some(conv) = stream.next_conversation()? { /* … */ }

    // One-shot inflate for custom parsing
    let bytes = lazy_sync.decompress()?;
}

Arc<Event> dispatch

With Arc<Event> dispatch, each event is wrapped in a single Arc by the CoreEventBus and shared across all handlers. This eliminates deep clones of large event payloads like LazyHistorySync blobs and Messages(MessageBatch). Both the wa::Message body and the MessageInfo inside each InboundMessage are Arc-wrapped, enabling zero-cost sharing across the message dispatch, durability hook, retry receipt, and PDO recovery paths without cloning the full struct — the batch handed to a registered durability hook is the very same Arc<[InboundMessage]> this event carries. Combined with LazyHistorySync’s OnceLock, all handlers sharing the same Arc<Event> get parse-once semantics for free — the first handler to call lazy_sync.get() triggers the decode, and subsequent handlers reuse the cached result.

Best Practices

Event Filtering

.on_event(|event, client| async move {
    // Only handle events you care about
    for InboundMessage { message: msg, info, .. } in event.messages() {
        // These are independent filters, not mutually exclusive cases —
        // a non-self-sent group message enters both blocks.
        if info.source.is_group {
            // Only handle group messages
        }
        if !info.source.is_from_me {
            // Only handle messages from others
        }
    }
})

Error Handling

.on_event(|event, client| async move {
    if let Err(e) = handle_event(&event, client).await {
        eprintln!("Event handler error: {}", e);
    }
})

async fn handle_event(event: &Event, client: Arc<Client>) -> Result<()> {
    for InboundMessage { message: msg, info, .. } in event.messages() {
        process_message(msg, info, client.clone()).await?
    }
    Ok(())
}

Spawning Tasks

.on_event(|event, client| async move {
    if matches!(&*event, Event::Messages(_)) {
        let client = client.clone();
        let event = event.clone(); // Arc clone — O(1)

        tokio::spawn(async move {
            for InboundMessage { message: msg, info, .. } in event.messages() {
                process_message(msg, info, &client).await;
            }
        });
    }
})

Architecture

Understand the event bus system

Authentication

Learn about pairing events

Sending messages

Sending and receiving messages

Client API

Complete client API reference

​Overview

​Event system architecture

​CoreEventBus

​EventHandler Trait

​Typed event interest (skip boxing unwanted events)

​Event Enum

​Connection Events

​Connected

​Disconnected

​ConnectFailure

​TemporaryBan

​StreamReplaced

​LoggedOut

​StreamError

​Pairing Events

​PairingQrCode

​PairingCode

​PairingCodeRefresh

​PairingCodeError

​PairingQrCodesExhausted

​PairSuccess

​PairError

​PairPasskeyRequest

​PairPasskeyConfirmation

​PairPasskeyError

​QrScannedWithoutMultidevice

​ClientOutdated

​Message Events

​Messages

​Receipt

​UndecryptableMessage

​Notification

​ServerAck

​Presence Events

​ChatPresence

​Presence

​User update events

​PictureUpdate

​UserAboutUpdate

​RetiredPushNameUpdate

​SelfPushNameUpdated

​Group Events

​GroupUpdate

​GroupNotificationAction

​Stale group metadata (groups_dirty)

​Contact notification events

​ContactUpdated

​ContactNumberChanged

​ContactSyncRequested

​ContactUpdate

​ContactRemoved

​Chat state events

​PinUpdate

​MuteUpdate

​ArchiveUpdate

​StarUpdate

​MarkChatAsReadUpdate

​DeleteChatUpdate

​ClearChatUpdate

​UserStatusMuteUpdate

​DeleteMessageForMeUpdate

​LabelEditUpdate

​LabelAssociationUpdate

​MessageLabelAssociationUpdate

​QuickReplyUpdate

​History sync events

​HistorySync

​HistorySyncStream

​OfflineSyncPreview

​OfflineSyncCompleted

​OfflineSyncInterrupted

​DirtyState

​AppStateSyncFailed

​ClientExpirationChanged

​Device Events

​DeviceListUpdate

​IdentityChange

​Implicit (locally-detected) identity changes

​BusinessStatusUpdate

​Newsletter Events

Overview

Event system architecture

CoreEventBus

EventHandler Trait

Typed event interest (skip boxing unwanted events)

Event Enum

Connection Events

Connected

Disconnected

ConnectFailure

TemporaryBan

StreamReplaced

LoggedOut

StreamError

Pairing Events

PairingQrCode

PairingCode

PairingCodeRefresh

PairingCodeError

PairingQrCodesExhausted

PairSuccess

PairError

PairPasskeyRequest

PairPasskeyConfirmation

PairPasskeyError

QrScannedWithoutMultidevice

ClientOutdated

Message Events

Messages

Receipt

UndecryptableMessage

Notification

ServerAck

Presence Events

ChatPresence

Presence

User update events

PictureUpdate

UserAboutUpdate

`RetiredPushNameUpdate`

SelfPushNameUpdated

Group Events

GroupUpdate

GroupNotificationAction

Stale group metadata (`groups_dirty`)

Contact notification events

ContactUpdated

ContactNumberChanged

ContactSyncRequested

ContactUpdate

ContactRemoved

Chat state events

PinUpdate

MuteUpdate

ArchiveUpdate

StarUpdate

MarkChatAsReadUpdate

DeleteChatUpdate

ClearChatUpdate

UserStatusMuteUpdate

DeleteMessageForMeUpdate

LabelEditUpdate

LabelAssociationUpdate

MessageLabelAssociationUpdate

QuickReplyUpdate

History sync events

HistorySync

HistorySyncStream

OfflineSyncPreview

OfflineSyncCompleted

OfflineSyncInterrupted

DirtyState

AppStateSyncFailed

ClientExpirationChanged

Device Events

DeviceListUpdate

IdentityChange

Implicit (locally-detected) identity changes

BusinessStatusUpdate

Newsletter Events