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

Each persisted operation lives in its own module under wacore::iq::mex_operations. Every module exposes:

NAME — the operation name (e.g. "WAWebJoinNewsletterMutation").
DOC_ID — the current persisted document ID.
OPERATION_KIND — "query" or "mutation".
VARIABLE_KEYS — every variable name the persisted document declares, e.g. &["fetch_viewer_metadata", "fetch_full_image", ...].
Variables — a typed struct matching the operation’s input shape.
Response — a typed struct matching the operation’s output shape.

Construct a MexRequest with MexRequest::new using those constants and a Variables value:

use wacore::iq::mex_operations::fetch_newsletter;
use whatsapp_rust::features::mex::MexRequest;

let request = MexRequest::new(
    fetch_newsletter::NAME,
    fetch_newsletter::DOC_ID,
    fetch_newsletter::VARIABLE_KEYS,
    fetch_newsletter::Variables {
        input: Some(fetch_newsletter::Input {
            key: Some(jid.to_string()),
            r#type: Some("JID".into()),
            view_role: Some("GUEST".into()),
        }),
        fetch_viewer_metadata: Some(true),
        fetch_full_image: Some(true),
        fetch_creation_time: Some(true),
        fetch_pinned_messages: Some(false),
        fetch_status_metadata: Some(false),
        fetch_wamo_sub: Some(false),
    },
);

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

A generated Variables does not implement Default. The server binds a persisted query’s variables by name and answers a bare 400 Bad Request when it can’t bind one of them, so every variable the operation declares has to be named at the call site — ..Default::default() does not compile, and neither does Variables::default(). Passing None for an Option field is still how you send a variable WhatsApp Web itself omits; nested input objects (for example Updates on update_newsletter) are unaffected and keep Default.

For operations whose Variables schema is too permissive to model exactly, pass any serde::Serialize value (for example a serde_json::json!({...})) as the variables — query and mutate are generic over V: Serialize. Use MexRequest::missing_variables to check such a payload against VARIABLE_KEYS, since the compiler can’t.

Methods

query

Execute a GraphQL query.

pub async fn query<V: Serialize>(
    &self,
    request: MexRequest<V>,
) -> Result<MexResponse, MexError>

mutate

Execute a GraphQL mutation.

pub async fn mutate<V: Serialize>(
    &self,
    request: MexRequest<V>,
) -> Result<MexResponse, MexError>

Example — mutation with typed variables:

use wacore::iq::mex_operations::join_newsletter;
use whatsapp_rust::features::mex::MexRequest;

let request = MexRequest::new(
    join_newsletter::NAME,
    join_newsletter::DOC_ID,
    join_newsletter::VARIABLE_KEYS,
    join_newsletter::Variables {
        newsletter_id: Some(jid.to_string()),
    },
);

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

Example — loosely-typed variables with serde_json:

use serde_json::json;
use wacore::iq::mex::MexDoc;
use whatsapp_rust::features::mex::MexRequest;

let request = MexRequest {
    doc: MexDoc {
        name: "WAWebUpdateGroupPropertyMutation",
        id: "8014515568645029",
    },
    declared_variables: &["group_id", "property", "value"],
    variables: json!({
        "group_id": group_jid.to_string(),
        "property": "announcement",
        "value": true,
    }),
};

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

fetch_new_chat_message_capping_info

Fetch the cap on how many new one-on-one conversations you can start in the current cycle.

pub async fn fetch_new_chat_message_capping_info(
    &self,
) -> Result<NewChatMessageCapping, MexError>

WhatsApp Web issues this request at app launch. It refreshes the cap on a TTL (wa_individual_new_chat_msg_capping_fetch_ttl_seconds, 1 hour), gated on wa_individual_new_chat_msg_capping_enabled. If the cap doesn’t apply to your account, you still get an answer — the status just reports NONE. Example:

use whatsapp_rust::CappingStatus;

let capping = client.mex().fetch_new_chat_message_capping_info().await?;

match &capping.capping_status {
    Some(CappingStatus::Capped) => println!("New-chat cap reached for this cycle"),
    Some(status) => println!("Capping status: {:?}", status),
    None => {}
}

if let Some(remaining) = capping.remaining_quota() {
    println!("{} new chats left this cycle", remaining);
}

get_username

Read this account’s own username, its state, and its username key.

pub async fn get_username(&self) -> Result<Option<OwnUsername>, MexError>

Returns:

None — no username is set on this account. WhatsApp Web reads the same 404 the server sends for this case.
Some(OwnUsername) — the account’s username info.

Only reads are exposed. set_username and set_username_key are not wrapped. They change the account’s identity in a way the server does not undo. A wrong call can burn a handle that someone else could otherwise take, and there is no way to test either safely.

Example:

match client.mex().get_username().await? {
    Some(own) => println!("Username: {:?} (state: {:?})", own.username, own.state),
    None => println!("No username set on this account"),
}

Types

MexDoc

A persisted-query descriptor. Re-exported from wacore::iq::mex.

pub struct MexDoc {
    /// Human-readable operation name (stable across bundle releases).
    pub name: &'static str,
    /// Numeric persisted-query ID (rotates with bundle releases).
    pub id: &'static str,
}

MexRequest

A persisted-query descriptor plus its typed variables. V is the variables type — usually the generated Variables struct for an operation, but any Serialize value works.

pub struct MexRequest<V> {
    pub doc: MexDoc,
    pub declared_variables: &'static [&'static str],
    pub variables: V,
}

declared_variables — the variable names the persisted document declares (an operation module’s VARIABLE_KEYS), carried so missing_variables can check a payload against them even when variables is a loosely-typed Serialize value.

new

Pair an operation’s NAME, DOC_ID, and VARIABLE_KEYS with its variables. Prefer this over building MexRequest as a struct literal.

pub fn new(
    name: &'static str,
    id: &'static str,
    declared_variables: &'static [&'static str],
    variables: V,
) -> MexRequest<V>

missing_variables

Declared variables this request’s payload does not carry, found by serializing variables and checking which of declared_variables are absent.

pub fn missing_variables(&self) -> Result<Vec<&'static str>, serde_json::Error>

A non-empty result isn’t automatically wrong — WhatsApp Web itself omits an optional variable it has no value for, and this reports that the same way rather than judging it. It exists mainly for the loosely-typed Serialize form of a request, where the compiler can’t check a json! payload against the operation’s declared variables the way it checks a Variables struct literal.

let request = MexRequest::new(
    fetch_all_newsletters_metadata::NAME,
    fetch_all_newsletters_metadata::DOC_ID,
    fetch_all_newsletters_metadata::VARIABLE_KEYS,
    json!({ "fetch_wamo_sub": false }),
);

assert_eq!(request.missing_variables()?, vec!["fetch_status_metadata"]);

MexResponse

Response from a GraphQL operation.

pub struct MexResponse {
    /// Response data (if successful).
    pub data: Option<serde_json::Value>,
    /// List of errors (if any).
    pub errors: Option<Vec<MexGraphQLError>>,
}

Methods:

has_data() — true if the response contains data.
has_errors() — true if the response contains errors.
fatal_error() — the first fatal error (any error with an error_code), if any.

MexGraphQLError

pub struct MexGraphQLError {
    pub message: String,
    pub extensions: Option<MexErrorExtensions>,
}

Methods:

error_code() — the numeric error code, if present.
is_summary() — true when the error is marked as a summary.
has_error_code() — true when an error code is set.

MexGraphQLError is re-exported from the crate root as whatsapp_rust::MexGraphQLError, alongside MexError, MexErrorExtensions, MexFatalError, MexRequest, MexResponse, and OwnUsername.

MexErrorExtensions

pub struct MexErrorExtensions {
    pub error_code: Option<i32>,
    pub is_summary: Option<bool>,
    pub is_retryable: Option<bool>,
    pub severity: Option<String>,
}

MexFatalError

The typed cause behind a fatal GraphQL error, from wacore::iq::mex. WhatsApp Web treats a GraphQL error carrying an extension code as fatal to the whole request. This struct is what lets that code survive the trip through IqError::ParseError’s source() chain instead of being flattened into a plain message.

#[non_exhaustive]
pub struct MexFatalError {
    pub query: &'static str,
    pub code: i32,
    pub message: String,
}

You won’t normally construct or match this directly. query/mutate already downcast it for you and hand back MexError::ExtensionError. It’s public for callers working with wacore::iq::mex::MexQuerySpec directly, below the whatsapp_rust::features::mex::Mex wrapper.

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.

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.

pub enum CappingOteStatus {
    NotEligible,
    Eligible,
    ActiveInCurrentCycle,
    Exhausted,
    Other(String),
}

CappingMvStatus

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

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

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),
}

query and mutate automatically convert any fatal GraphQL error (any error with an error_code) into MexError::ExtensionError. This lets you match on it without inspecting response.errors yourself. This now happens for every MEX operation via a typed MexFatalError carried inside IqError::ParseError’s source chain. Previously the code could be lost, surfacing only as a message inside MexError::Request(IqError::ParseError(_)).

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

match client.mex().query(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.

Response handling

Check for data

let response = client.mex().query(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().query(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 wacore::iq::mex_operations::fetch_newsletter;

let response = client.mex().query(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

Methods

query

mutate

fetch_new_chat_message_capping_info

get_username

Types

MexDoc

MexRequest

new

missing_variables

MexResponse

MexGraphQLError

MexErrorExtensions

MexFatalError

OwnUsername

NewChatMessageCapping

CappingStatus

CappingOteStatus

CappingMvStatus

Error handling

Response handling

Check for data

Handle non-fatal errors

Decode the typed response

​Access

​Building a request

​Methods

​query

​mutate

​fetch_new_chat_message_capping_info

​get_username

​Types

​MexDoc

​MexRequest

​new

​missing_variables

​MexResponse

​MexGraphQLError

​MexErrorExtensions

​MexFatalError

​OwnUsername

​NewChatMessageCapping

​CappingStatus

​CappingOteStatus

​CappingMvStatus

​Error handling

​Response handling

​Check for data

​Handle non-fatal errors

​Decode the typed response

Access

Building a request

Methods

query

mutate

fetch_new_chat_message_capping_info

get_username

Types

MexDoc

MexRequest

new

missing_variables

MexResponse

MexGraphQLError

MexErrorExtensions

MexFatalError

OwnUsername

NewChatMessageCapping

CappingStatus

CappingOteStatus

CappingMvStatus

Error handling

Response handling

Check for data

Handle non-fatal errors

Decode the typed response