MEX (GraphQL)

The Mex feature wraps WhatsApp’s Meta Exchange (MEX) GraphQL API. Operations are persisted: you reference each query or mutation by a (name, id) pair pulled from a generated operation module, and pass its typed Variables. WhatsApp Web bundle updates rotate the numeric id, so the human-readable name keeps diagnostics stable across releases.

Access

let mex = client.mex();

Building a request

use whatsapp_rust::{mex_operation, wacore::iq::mex_operations::join_newsletter};

let operation = mex_operation!(join_newsletter);
let mut variables = join_newsletter::Variables::default();
variables.newsletter_id = Some(jid.to_string());
let request = operation.request(variables);
let response = client.mex().execute(request).await?;

mex_operation! binds operation name, persisted document ID, declared keys, and generated variables type from the same module. An unrelated variables type fails to compile. Generated Variables, nested input/response shapes and response mirrors are non-exhaustive and implement Default. Construct with Default and assign the fields you need. External struct literals, including ..Default::default(), no longer compile. None omits a key where the serializer allows it; it supplies no protocol default or validation of server-required variables.

execute

Mex::execute(MexRequest<V>) is the shared path for queries and mutations, with V: Serialize. It serializes directly to wire bytes and returns MexResponse. Generated response mirrors are heuristic; use a domain parser before treating the payload as a feature contract. Use operation.raw_request(serializable_value) when a generated variables mirror cannot represent the intended input. The descriptor’s metadata stays bound to that operation. For custom persisted operations, MexOperation::from_raw_parts or MexRequest::new_raw is the explicit unchecked path; the host owns metadata consistency.

MexRequest

Metadata is private. Read it with doc() and declared_variables(); variables remains public. missing_variables() is an optional diagnostic that compares serialized top-level keys, including keys omitted by skip_serializing_if. It allocates a JSON value and is not automatically enforced on execution. A declared key is not proof of a required server variable.

Convenience operations

Use fetch_reachout_timelock, fetch_new_chat_message_capping_info, and get_username for the library’s parsed contracts. ReachoutTimelockUpdate delivers parsed push updates separately from these reads. See events.

Types

OwnUsername

This account’s own Meta username, as get_username reports it. Every field is optional because the server omits the ones that don’t apply.

#[non_exhaustive]
pub struct OwnUsername {
    /// The handle, without the display-only `@` prefix.
    pub username: Option<String>,
    /// `ACTIVE` or `RESERVED`.
    pub state: Option<String>,
    /// The numeric username key that guards lookups of this account by handle.
    pub key: Option<String>,
}

NewChatMessageCapping

How many new one-on-one conversations you can still start in the current cycle, and why. Every field is optional — the server omits any that don’t apply to your account’s tier.

#[non_exhaustive]
pub struct NewChatMessageCapping {
    pub capping_status: Option<CappingStatus>,
    pub ote_status: Option<CappingOteStatus>,
    pub mv_status: Option<CappingMvStatus>,
    pub total_quota: Option<u64>,
    pub used_quota: Option<u64>,
    pub cycle_start_timestamp: Option<i64>,
    pub cycle_end_timestamp: Option<i64>,
    pub server_sent_timestamp: Option<i64>,
}

total_quota / used_quota — new chats allowed / already started this cycle
cycle_start_timestamp / cycle_end_timestamp / server_sent_timestamp — Unix seconds. The cap lifts once cycle_end_timestamp passes.

Methods:

remaining_quota() -> Option<u64> — saturating subtraction of used_quota from total_quota, when both are present; returns Some(0) when used_quota exceeds total_quota

CappingStatus

Where you stand against the cap.

#[non_exhaustive]
pub enum CappingStatus {
    None,
    FirstWarning,
    SecondWarning,
    Capped,
    Other(String),
}

CappingOteStatus

Whether you’re eligible for the one-time extension that lifts the cap for a cycle.

#[non_exhaustive]
pub enum CappingOteStatus {
    NotEligible,
    Eligible,
    ActiveInCurrentCycle,
    Exhausted,
    Other(String),
}

CappingMvStatus

Your Meta Verified subscription state, which lifts the cap permanently.

#[non_exhaustive]
pub enum CappingMvStatus {
    NotEligible,
    NotActive,
    Active,
    ActiveUpgradeAvailable,
    Other(String),
}

NewChatMessageCapping, CappingStatus, CappingOteStatus, and CappingMvStatus are re-exported from the crate root, alongside the other Mex types.

Error handling

#[non_exhaustive]
pub enum MexError {
    /// Payload missing or malformed with only a descriptive message.
    PayloadParsing(String),
    /// Payload contained an invalid JID.
    InvalidJid(JidError),
    /// GraphQL error with a numeric code surfaced as a typed error.
    ExtensionError { code: i32, message: String },
    /// Underlying IQ request failed.
    Request(IqError),
    /// JSON serialization or deserialization error.
    Json(serde_json::Error),
}

execute converts a fatal GraphQL response into MexError::ExtensionError while preserving its numeric code. Fatal selection checks a summary error, then an error with error_code, then the first error with fallback code 500. The typed MexFatalError remains reachable through an IQ parse-error source chain at lower levels.

use whatsapp_rust::features::mex::MexError;

match client.mex().execute(request).await {
    Ok(response) => {
        if response.has_data() {
            println!("Success: {:?}", response.data);
        }
    }
    Err(MexError::ExtensionError { code, message }) => {
        eprintln!("MEX error {}: {}", code, message);
    }
    Err(e) => eprintln!("Request failed: {}", e),
}

get_username treats a fatal 404 as “no username set” rather than a failure. It arrives as either MexError::ExtensionError { code: 404, .. } or MexError::Request(IqError::ServerError { code: 404, .. }) — the two shapes WhatsApp Web’s own MEX client raises a 404 from. Either shape returns Ok(None) instead of an error.

MexFatalError

whatsapp_rust::wacore::iq::mex::MexFatalError retains the operation’s query: &'static str, numeric code: i32, and message: String. Use typed matching or source-chain inspection rather than parse its display text. Read the pinned MEX response parser for fatal selection and parsing.

Response handling

Check for data

let response = client.mex().execute(request).await?;

if response.has_data() {
    let data = response.data.unwrap();
    // Process data
}

Handle non-fatal errors

Errors without an error_code are non-fatal and surface in response.errors alongside any partial data.

let response = client.mex().execute(request).await?;

if response.has_errors() {
    for error in response.errors.as_ref().unwrap() {
        if !error.is_summary() && !error.has_error_code() {
            eprintln!("Warning: {}", error.message);
        }
    }
}

Decode the typed response

Generated operation modules also expose a Response struct that mirrors the GraphQL schema. Decode it from response.data with serde_json:

use whatsapp_rust::wacore::iq::mex_operations::fetch_newsletter;

let response = client.mex().execute(request).await?;

if let Some(data) = response.data {
    let decoded: fetch_newsletter::Response = serde_json::from_value(data)?;
    if let Some(newsletter) = decoded.xwa2_newsletter {
        println!("Newsletter: {:?}", newsletter);
    }
}

The persisted DOC_ID for each operation is regenerated from the latest WhatsApp Web bundle. Pin to a specific crate version if you need a stable wire format.

Core

Messaging

Features

Storage & Backends

Core Modules

Access

Building a request

execute

MexRequest

Convenience operations

Types

OwnUsername

NewChatMessageCapping

CappingStatus

CappingOteStatus

CappingMvStatus

Error handling

MexFatalError

Response handling

Check for data

Handle non-fatal errors

Decode the typed response

​Access

​Building a request

​execute

​MexRequest

​Convenience operations

​Types

​OwnUsername

​NewChatMessageCapping

​CappingStatus

​CappingOteStatus

​CappingMvStatus

​Error handling

​MexFatalError

​Response handling

​Check for data

​Handle non-fatal errors

​Decode the typed response

Access

Building a request

execute

MexRequest

Convenience operations

Types

OwnUsername

NewChatMessageCapping

CappingStatus

CappingOteStatus

CappingMvStatus

Error handling

MexFatalError

Response handling

Check for data

Handle non-fatal errors

Decode the typed response