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".
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::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),
    },
);

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

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.

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::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",
    },
    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);
}

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 variables: V,
}

new

Pair an operation’s NAME and DOC_ID with its variables.

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

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, MexRequest, and MexResponse.

MexErrorExtensions

pub struct MexErrorExtensions {
    pub error_code: Option<i32>,
    pub is_summary: Option<bool>,
    pub is_retryable: Option<bool>,
    pub severity: 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 so you can match on it without inspecting response.errors yourself.

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

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

Types

MexDoc

MexRequest

new

MexResponse

MexGraphQLError

MexErrorExtensions

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

​Types

​MexDoc

​MexRequest

​new

​MexResponse

​MexGraphQLError

​MexErrorExtensions

​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

Types

MexDoc

MexRequest

new

MexResponse

MexGraphQLError

MexErrorExtensions

NewChatMessageCapping

CappingStatus

CappingOteStatus

CappingMvStatus

Error handling

Response handling

Check for data

Handle non-fatal errors

Decode the typed response