Profile

The Profile feature provides methods for managing your own account’s display name, status text (about), and profile picture.

Access

Access profile operations through the client:

let profile = client.profile();

Methods

set_push_name

set_push_name(&str) returns Result<PushNameOutcome, ProfileError>. An empty name is rejected. A presence transport failure returns an error before changing the local name. Otherwise, the client attempts app-state synchronization and updates the local name. Synced means the app-state step completed. SyncPending { source } retains the original AppStateError after presence was sent and the local name updated. Neither outcome proves that every linked device displays the name or that all local state is durable. Transport acceptance is not a server ACK.

use whatsapp_rust::{Client, ProfileError, PushNameOutcome};

async fn set_name(client: &Client, name: &str) -> Result<PushNameOutcome, ProfileError> {
    let outcome = client.profile().set_push_name(name).await?;
    match &outcome {
        PushNameOutcome::Synced => println!("Push-name synchronization completed"),
        PushNameOutcome::SyncPending { source } => {
            eprintln!("Push-name synchronization pending: {source}");
        }
        _ => {}
    }
    Ok(outcome)
}

Retain the desired name with a pending outcome so your retry policy can act on its cause. Pending synchronization is possible during pairing before app-state keys arrive.

sync_push_name

sync_push_name(&str) returns Result<(), AppStateError>. Retry this step after the connection or keys become available. It sends only the app-state mutation, without resending presence or changing the local name. Retry only if the pending name is still desired; do not overwrite a newer choice.

use whatsapp_rust::{Client, AppStateError};

async fn retry_name_sync(client: &Client, pending_name: &str) -> Result<(), AppStateError> {
    client.profile().sync_push_name(pending_name).await
}

set_text_status

Set your About text, with an optional emoji and an explicit expiry. This uses the text-status MEX mutation.

pub async fn set_text_status(
    &self,
    text: &str,
    emoji: Option<&str>,
    expiry: TextStatusExpiry,
) -> Result<(), ProfileError>

use whatsapp_rust::TextStatusExpiry;

client.profile().set_text_status("Available", None, TextStatusExpiry::Never).await?;

Use TextStatusExpiry::After(std::time::Duration::from_secs(3600)) for an expiring About. Durations must be at least one second. ProfileError::Mex preserves a failed mutation.

clear_text_status

client.profile().clear_text_status().await? sends null text with zero duration to remove the About.

set_status_text

set_status_text(&str) remains available for the legacy status IQ. A successful IQ does not establish that phone clients display the new About. Prefer set_text_status. These operations are separate from audience-selected status posts.

set_profile_picture

Set your profile picture.

pub async fn set_profile_picture(
    &self,
    image_data: Vec<u8>
) -> Result<SetProfilePictureResponse, ProfileError>

Parameters:

image_data - JPEG image bytes

Returns:

SetProfilePictureResponse - Contains the new picture ID

The image should already be properly sized/cropped by the caller. WhatsApp typically uses 640x640 images. Example:

use std::fs;

let image_bytes = fs::read("profile.jpg")?;
let response = client.profile().set_profile_picture(image_bytes).await?;
println!("New picture ID: {:?}", response.id);

The image must be a valid JPEG. Other formats are not supported.

remove_profile_picture

Remove your profile picture.

pub async fn remove_profile_picture(&self) -> Result<SetProfilePictureResponse, ProfileError>

Returns:

SetProfilePictureResponse - Confirmation of removal

Example:

client.profile().remove_profile_picture().await?;

Since v0.6 the remove IQ omits the <picture/> child entirely, matching WA Web’s SendProfilePictureJob. Sending an empty <picture> child was rejected by some hosts.

Types

SetProfilePictureResponse

Response from profile picture operations.

pub struct SetProfilePictureResponse {
    /// The server-assigned picture ID.
    pub id: String,
}

Retain pending synchronization

The set_name helper above returns the outcome to its caller. Store the pending name and cause before starting unrelated profile operations, so a later picture or status-text failure cannot discard the synchronization result.

Error handling

Profile updates return Result<T, ProfileError>; the app-state-only retry returns Result<(), AppStateError>:

#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum ProfileError {
    #[error("{0}")]
    Iq(#[from] IqError),
    #[error("{0}")]
    Client(#[from] ClientError),
    #[error("invalid argument: {0}")]
    InvalidArgument(String),
    #[error("{0}")]
    Internal(#[from] anyhow::Error),
}

Common errors:

InvalidArgument — e.g., empty push name
Iq — server rejected the status text or picture IQ
Client(ClientError::NotLoggedIn) — not authenticated
Internal — network errors, encoding failures

use whatsapp_rust::ProfileError;

match client.profile().set_push_name("").await {
    Ok(outcome) => println!("Inspect name outcome: {outcome:?}"),
    Err(ProfileError::InvalidArgument(msg)) => eprintln!("Invalid: {}", msg),
    Err(e) => eprintln!("Failed: {}", e),
}

Core

Messaging

Features

Storage & Backends

Core Modules

Access

Methods

set_push_name

sync_push_name

set_text_status

clear_text_status

set_status_text

set_profile_picture

remove_profile_picture

Types

SetProfilePictureResponse

Retain pending synchronization

Error handling

See also

​Access

​Methods

​set_push_name

​sync_push_name

​set_text_status

​clear_text_status

​set_status_text

​set_profile_picture

​remove_profile_picture

​Types

​SetProfilePictureResponse

​Retain pending synchronization

​Error handling

​See also

Access

Methods

set_push_name

sync_push_name

set_text_status

clear_text_status

set_status_text

set_profile_picture

remove_profile_picture

Types

SetProfilePictureResponse

Retain pending synchronization

Error handling

See also