Contacts

Examples on this page target source snapshot 35a69a14, not a crates.io release. Use the current API guide to select the matching dependency.

The Contacts struct provides methods for checking WhatsApp registration status and retrieving profile pictures and user information.

Access

Access contact operations through the client:

let contacts = client.contacts();

Methods

is_on_whatsapp

Check if JIDs are registered on WhatsApp. Accepts both PN JIDs and LID JIDs.

pub async fn is_on_whatsapp(
    &self,
    jids: &[Jid],
) -> Result<Vec<IsOnWhatsAppResult>, ContactError>

Parameters:

jids - Array of JIDs to check. Supports Jid::pn("phone_number") for phone number lookups and Jid::lid("lid_value") for LID lookups. If you pass a non-PN/non-LID JID (groups, newsletters, etc.), the method returns an error immediately.

Returns:

Vec<IsOnWhatsAppResult> - Registration status for each JID

IsOnWhatsAppResult fields:

jid: Jid - WhatsApp JID for the user
is_registered: bool - Whether the JID is on WhatsApp
lid: Option<Jid> - LID (Linked Identity) if available
pn_jid: Option<Jid> - Phone number JID, present when the server returns LID as the primary JID
is_business: bool - Whether this is a WhatsApp Business account
verified_name: Option<VerifiedName> - Decoded verified business name certificate, when the account is a verified business
username: Option<CompactString> - Meta username, without the display-only @ prefix. None means the server reported no username, which is also how it reports one that was deleted; it is never an empty string
contact_error: Option<UsyncSubprotocolError> - Server error for the contact subprotocol (e.g. privacy-blocked lookup); is_registered will be false
lid_error: Option<UsyncSubprotocolError> - Server error for the lid subprotocol; lid will be None
business_error: Option<UsyncSubprotocolError> - Server error for the business subprotocol; is_business will be false
username_error: Option<UsyncSubprotocolError> - Server error for the username subprotocol. Unlike the other *_error fields, this does not imply username is None. The server also publishes a username as a plain attribute of the contact result, and a failed subprotocol does not retract that value. So username can still be Some next to username_error.

VerifiedName fields:

name: Option<String> - Display name shown to other users (decoded from the certificate when the server omits the attribute)
serial: Option<String> - Certificate serial number
issuer: Option<String> - Certificate issuer
certificate: Option<Vec<u8>> - Raw VerifiedNameCertificate protobuf bytes, for callers that need to verify the signature themselves

IsOnWhatsAppResult is marked #[non_exhaustive], so new fields may be added in future versions without a breaking change.

Both is_on_whatsapp and get_user_info now ask for the username subprotocol by default, matching WhatsApp Web’s own existence check and background contact sync. This is not opt-in and adds one more child to the <query> node of both requests.

Example — phone number lookup:

let results = client.contacts().is_on_whatsapp(&[
    Jid::pn("15551234567"),
    Jid::pn("15559876543"),
]).await?;

for result in results {
    if result.is_registered {
        println!("{} is on WhatsApp", result.jid);
        if let Some(lid) = &result.lid {
            println!("  LID: {}", lid);
        }
        if result.is_business {
            println!("  Business account");
            if let Some(vn) = &result.verified_name
                && let Some(name) = &vn.name
            {
                println!("  Verified name: {}", name);
            }
        }
    } else {
        println!("{} is NOT on WhatsApp", result.jid);
    }
}

Example — LID lookup:

let results = client.contacts().is_on_whatsapp(&[
    Jid::lid("100000001"),
]).await?;

for result in results {
    if let Some(pn) = &result.pn_jid {
        println!("LID {} maps to phone {}", result.jid, pn);
    }
}

PN and LID queries use different wire protocols (matching WhatsApp Web’s ExistsJob), so mixed inputs are automatically split into separate requests. LID-PN mappings discovered from results are persisted to the local cache.

Profile pictures

Use the pictures facade for single contact, group or community lookups. Choose an explicit route and size and preserve unchanged, missing, unauthorized and error outcomes.

get_user_info

Get user information by JID.

pub async fn get_user_info(
    &self,
    jids: &[Jid],
) -> Result<HashMap<Jid, UserInfo>, ContactError>

Parameters:

jids - Array of JIDs to query

The system/announcements JID (0@s.whatsapp.net, and its legacy form 0@c.us) is filtered out of the batch before it’s sent — it’s not usync-eligible and the server never answers for it. If it’s the only JID passed in, get_user_info returns an empty map without making a request; if it’s mixed with other JIDs, the remaining JIDs are still queried normally.

Returns:

HashMap<Jid, UserInfo> - Map of JID to user info

UserInfo fields:

jid: Jid - WhatsApp JID
lid: Option<Jid> - LID if available
lid_error: Option<UsyncSubprotocolError> - Server error for the lid subprotocol; lid will be None
status: Option<String> - Status message
status_error: Option<UsyncSubprotocolError> - Server error for the status subprotocol (e.g. privacy-hidden status); status will be None
picture_id: Option<String> - Profile picture ID
picture_error: Option<UsyncSubprotocolError> - Server error for the picture subprotocol; picture_id will be None
is_business: bool - Whether business account
business_error: Option<UsyncSubprotocolError> - Server error for the business subprotocol; is_business will be false
verified_name: Option<VerifiedName> - Decoded verified business name certificate, for verified business accounts (see is_on_whatsapp for field details)
devices: Vec<u16> - Device IDs from the <devices version="2"> sublist the same usync query returns (device 0 is the primary). Empty when the server omits the sublist — no extra request is needed.
devices_error: Option<UsyncSubprotocolError> - Server error for the devices subprotocol; devices will be empty
username: Option<CompactString> - Meta username, without the display-only @ prefix. See IsOnWhatsAppResult::username for how it’s sourced and what None means
username_error: Option<UsyncSubprotocolError> - Server error for the username subprotocol. See IsOnWhatsAppResult::username_error — a value already read from the contact result’s attribute survives next to this error

UserInfo is #[non_exhaustive], so new fields may be added in future versions without a breaking change.

UsyncSubprotocolError fields:

code: Option<u16> - Numeric error code from the server (e.g. 403, 404)
text: Option<String> - Human-readable error description
backoff: Option<u32> - Server-suggested retry delay in seconds

The library preserves per-subprotocol errors on the result struct rather than failing the whole request. A privacy error from one user’s status does not block retrieval of devices for other users in the same batch. Check the *_error fields when a corresponding Option field is None and you need to distinguish “not set” from “server error”.

let user_info = client.contacts().get_user_info(&[jid]).await?;
if let Some(info) = user_info.get(&jid) {
    if info.status.is_none() {
        if let Some(err) = &info.status_error {
            println!("Status hidden: code={:?} text={:?}", err.code, err.text);
        }
    }
}

Example:

let jids = vec![
    "15551234567@s.whatsapp.net".parse()?,
    "15559876543@s.whatsapp.net".parse()?,
];

let user_info = client.contacts().get_user_info(&jids).await?;

for (jid, info) in user_info {
    println!("User: {}", jid);
    println!("  Business: {}", info.is_business);
    println!("  Devices: {:?}", info.devices); // e.g. [0, 1, 2]

    if let Some(vn) = &info.verified_name
        && let Some(name) = &vn.name
    {
        println!("  Verified name: {}", name);
    }

    if let Some(status) = info.status {
        println!("  Status: {}", status);
    }

    if let Some(pic_id) = info.picture_id {
        println!("  Picture ID: {}", pic_id);
    }
}

find_by_username

Resolve a Meta username to the account behind it.

pub async fn find_by_username(
    &self,
    username: &str,
    username_key: Option<&str>,
) -> Result<UsernameLookup, ContactError>

Parameters:

username - The handle to resolve. A leading @ is display-only and is stripped automatically. The bare handle must be between USERNAME_MIN_LENGTH (3) and USERNAME_MAX_LENGTH (35) characters, or the call fails with ContactError::Username before any request is sent.
username_key - The account’s numeric “username key” (WhatsApp Web calls it a pin). Some accounts require it before the server will disclose the identity behind their handle at all.

Returns: UsernameLookup:

NotFound - No account answers to this username, or it’s not reachable from here
KeyRequired { username: Option<CompactString> } - The username exists but the server withheld the identity; repeat the call with the account’s username key
Found(UsernameLookupUser) - The username resolved to an account

UsernameLookupUser fields:

jid: Jid - Identity the server returned. The query addresses contacts by LID, so this is normally a LID
pn_jid: Option<Jid> - Phone-number JID, when the server disclosed one on <business>
username: Option<CompactString> - Username as the server spelled it back
is_business: bool
verified_name: Option<VerifiedName>

On Found, the discovered LID/PN pair is persisted to the local cache, the same way is_on_whatsapp and get_user_info do.

Experimental. The request is built exactly as WhatsApp Web’s WAWebQueryExistsJob.queryUsernameExists builds it. No capture of a live server answering it backs this implementation — only the request shape is verified against the official client. A server that rejects the query is not necessarily a bug here.

Example:

use whatsapp_rust::UsernameLookup;

match client.contacts().find_by_username("example.handle", None).await? {
    UsernameLookup::Found(user) => {
        println!("Resolved to {}", user.jid);
        if let Some(pn) = &user.pn_jid {
            println!("  Phone number: {}", pn);
        }
    }
    UsernameLookup::KeyRequired { .. } => {
        println!("This account requires its username key to resolve");
    }
    UsernameLookup::NotFound => println!("No account answers to that username"),
}

Types

Privacy & TC tokens

For user JIDs (not groups/newsletters), the library automatically includes TC tokens when fetching profile pictures. TC tokens are used for privacy-gated operations. The implementation automatically:

Looks up TC tokens for user JIDs
Includes tokens in profile picture requests
Skips tokens for groups and newsletters

get_user_info does the same for status/about: when the profile_scraping_privacy_token_in_about_usync AB prop is on, each queried JID’s TC token is attached to its <user> node in the usync IQ, matching WhatsApp Web’s USyncStatusProtocol. This is what lets status/status_error and about resolve correctly for a privacy-restricted contact instead of coming back hidden. See TC Token for details.

Async compatibility

is_on_whatsapp and get_user_info work correctly when called from #[async_trait] implementations or any context that boxes the returned future (Box<dyn Future + Send>). Earlier versions produced a compile error ("implementation of FnOnce is not general enough") that could not be worked around in user code. Fixed in #826 with no API changes.

Error handling

All methods return Result<T, ContactError>:

#[non_exhaustive]
pub enum ContactError {
    #[error("{0}")]
    Iq(#[from] IqError),
    #[error("unsupported contact JID: {0}")]
    InvalidJid(String),
    #[error("{0}")]
    Username(#[from] UsernameLookupError),
}

Username is returned by find_by_username when the handle can’t be turned into a valid lookup — too short, too long, or a username_key that fails usync’s own field-consistency validation.

#[non_exhaustive]
pub enum UsernameLookupError {
    #[error("username length {length} is outside the {USERNAME_MIN_LENGTH}..={USERNAME_MAX_LENGTH} the server accepts")]
    InvalidLength { length: usize },
    #[error("the username query is not a valid usync query: {0}")]
    Query(#[from] UsyncValidationError),
}

use whatsapp_rust::ContactError;

match client.contacts().is_on_whatsapp(&[jid]).await {
    Ok(results) => { /* ... */ }
    Err(ContactError::Iq(e)) => eprintln!("Server error: {}", e),
    Err(e) => eprintln!("Error: {}", e),
}

Batch operations

All lookup methods support batch operations for efficiency:

// Check multiple JIDs at once
let results = client.contacts().is_on_whatsapp(&[
    Jid::pn("15551111111"),
    Jid::pn("15552222222"),
    Jid::pn("15553333333"),
]).await?;

// Get info for multiple JIDs
let jids = vec![
    "15551111111@s.whatsapp.net".parse()?,
    "15552222222@s.whatsapp.net".parse()?,
];
let user_info = client.contacts().get_user_info(&jids).await?;

Contact notification events

The server sends contacts notifications when contact data changes. These are emitted as events you can subscribe to:

ContactUpdated — a contact’s profile changed (invalidate cached presence/profile picture)
ContactNumberChanged — a contact changed their phone number (includes old/new JID and optional LID mappings)
ContactSyncRequested — the server requests a full contact re-sync

Event::ContactUpdated(update) => {
    // Refresh cached profile data for update.jid
}
Event::ContactNumberChanged(change) => {
    // Migrate chat data from change.old_jid to change.new_jid
}
Event::ContactSyncRequested(sync) => {
    // Re-sync contacts (optionally filtered by sync.after timestamp)
}

See the events reference for full struct definitions and wire format details.

These are server-push notifications, distinct from ContactUpdate and ContactRemoved, which come from app-state sync mutations made on a linked device. See Chat actions — Save and remove contacts for save_contact/remove_contact and their events.

Empty input handling

Passing empty arrays returns empty results without making network requests:

let empty: Vec<Jid> = vec![];
let results = client.contacts().is_on_whatsapp(&empty).await?;
assert!(results.is_empty());

Migration from previous versions

The is_on_whatsapp method previously accepted &[&str] (phone number strings). It now takes &[Jid]:

// Before
let results = client.contacts().is_on_whatsapp(&["1234567890"]).await?;

// After
let results = client.contacts().is_on_whatsapp(&[Jid::pn("1234567890")]).await?;

The get_info method and ContactInfo type have been removed. Use is_on_whatsapp for registration checks (now includes lid, pn_jid, and is_business fields) or get_user_info for detailed profile data (status, picture ID).

Learning LID and phone aliases

On main snapshot 35a69a14, contact lookups learn PN-primary results with LID fields and LID-primary results with explicit PN fields, including business usync responses. The client validates the identity families and user identifiers before storing a pair. Mapping persistence errors are logged; a successful contact lookup does not itself prove that an alias reached durable storage. App-state contact actions also persist validated LID/PN pairs before advancing their collection cursor or publishing observations. A mapping write failure leaves that update retryable. Multiple retained mappings keep deterministic application order and the existing last-LID-per-phone policy. A learned alias helps routing and lookup. It does not authorize rewriting a stored cryptographic creator or merging unrelated message IDs. Preserve the original creator for polls, events and encrypted message actions, and keep consumer deduplication scoped by chat, sender and ID. Startup PN/LID warm-up preserves newer live mappings learned while backend reads are in flight. Treat cached aliases as validated observations with provenance, not authority to rewrite original cryptographic creators or message IDs. A completed lookup still does not prove durable persistence of a learned pair.

Core

Messaging

Features

Storage & Backends

Core Modules

Access

Methods

is_on_whatsapp

Profile pictures

get_user_info

find_by_username

Types

Privacy & TC tokens

Async compatibility

Error handling

Batch operations

Contact notification events

Empty input handling

Migration from previous versions

Learning LID and phone aliases

​Access

​Methods

​is_on_whatsapp

​Profile pictures

​get_user_info

​find_by_username

​Types

​Privacy & TC tokens

​Async compatibility

​Error handling

​Batch operations

​Contact notification events

​Empty input handling

​Migration from previous versions

​Learning LID and phone aliases

Access

Methods

is_on_whatsapp

Profile pictures

get_user_info

find_by_username

Types

Privacy & TC tokens

Async compatibility

Error handling

Batch operations

Contact notification events

Empty input handling

Migration from previous versions

Learning LID and phone aliases