Contacts

​

Access

let contacts = client.contacts();

​

Methods

​

is_on_whatsapp

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

• 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.

• Vec<IsOnWhatsAppResult> - Registration status for each JID

• 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.

• 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

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

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

​

get_profile_picture

pub async fn get_profile_picture(
    &self,
    jid: &Jid,
    preview: bool,
) -> Result<Option<ProfilePicture>, ContactError>

• jid - Target JID (user, group, or newsletter)
• preview - true for preview thumbnail, false for full-size image

• Option<ProfilePicture> - Picture info or None if not available

• id: String - Picture ID
• url: String - Download URL
• direct_path: Option<String> - Direct path for media download
• hash: Option<String> - SHA-256 hash for integrity and cache validation

let jid: Jid = "15551234567@s.whatsapp.net".parse()?;

// Get preview thumbnail
if let Some(preview) = client.contacts().get_profile_picture(&jid, true).await? {
    println!("Preview URL: {}", preview.url);
    println!("Picture ID: {}", preview.id);
}

// Get full-size picture
if let Some(full) = client.contacts().get_profile_picture(&jid, false).await? {
    println!("Full URL: {}", full.url);
    if let Some(path) = full.direct_path {
        println!("Direct path: {}", path);
    }
}

// Handle user with no profile picture
let no_pic_jid: Jid = "15559999999@s.whatsapp.net".parse()?;
if client.contacts().get_profile_picture(&no_pic_jid, true).await?.is_none() {
    println!("User has no profile picture");
}

let group_jid: Jid = "123456789@g.us".parse()?;
if let Some(pic) = client.contacts().get_profile_picture(&group_jid, true).await? {
    println!("Group picture: {}", pic.url);
}

​

get_user_info

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

• jids - Array of JIDs to query

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

• 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

• 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

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

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

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

• 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.

• 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

• 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>

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

​

Privacy & TC tokens

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

​

Async compatibility

​

Error handling

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

#[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

// 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

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

​

Empty input handling

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

​

Migration from previous versions

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

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