Groups

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

Choose a projection

Need	Entry point	Cost and result
List joined groups	`list_participating()`	Slim `GroupOverview` records; no participant collection
Display a chosen subset	`fetch_overviews(&[Jid])`	Network batch, no LID/PN backfill
Full group state	`fetch_metadata(&Jid)`	Full metadata, participant/address handling
Full chosen subset	`fetch_metadata_batch(&[Jid])`	Per-entry `GroupMetadataResult`, including truncation
Encrypt a group send	`routing_info(&Jid)`	Cached `Arc<GroupRoutingInfo>` with routing participants and addressing mode

Overview, metadata and routing are separate projections. Do not load full metadata for a list UI or use an overview as an encryption membership list. A batch result can be found, truncated, forbidden or absent; do not collapse every non-found result into a missing group.

list_participating

use whatsapp_rust::Client;

async fn list(client: &Client) -> whatsapp_rust::anyhow::Result<()> {
    for group in client.groups().list_participating().await? {
        println!("{}", group.id);
    }
    Ok(())
}

fetch_metadata

Fetch full metadata when you need participant roles, description tokens or detailed state. resolve_participant_addresses(&mut metadata) enriches participant addresses when needed by a custom workflow. Treat returned DTOs as extensible; match with .. rather than exhaustive destructuring.

routing_info

Use this projection for custom group fanout. Ordinary sends select routing themselves. Routing is not a display DTO and does not imply the full metadata cache is populated. The cache freshness policy is explicit in send options.

create_group

use whatsapp_rust::{Client, GroupCreateOptions, GroupParticipantOptions, Jid};

async fn create(client: &Client, participant: Jid) -> whatsapp_rust::anyhow::Result<()> {
    let options = GroupCreateOptions::new("Engineering")
        .with_participants(vec![GroupParticipantOptions::new(participant)]);
    let result = client.groups().create_group(options).await?;
    println!("{}", result.metadata.id);
    Ok(())
}

The non-exhaustive input requires a subject and has no Default. Use new or the builder with required fields. For an externally known LID participant, supply the PN association when available; missing required mappings are returned as an error. Mock full outputs with GroupMetadata::new(jid) and GroupParticipant::new(jid), then set supported fields. Do not write complete DTO literals that freeze their field list.

set_subject

Pass a validated GroupSubject. It rejects a blank or oversized subject before the mutation is sent.

set_description

use whatsapp_rust::{Client, GroupDescription, Jid, PreviousDescription};

async fn describe(client: &Client, group: &Jid) -> whatsapp_rust::anyhow::Result<()> {
    client.groups().set_description(
        group,
        Some(GroupDescription::new("Team discussions")?),
        PreviousDescription::Resolve,
    ).await?;
    Ok(())
}

Use None to remove the description. PreviousDescription::Resolve reads the current token first; Id(token) uses your known current token and Absent asserts there was no description. Handle GroupError::DescriptionConflict by reconciling current state, rather than overwriting an unseen concurrent change.

Participants and membership

Task	Entry points
Add participants	`add_participants`
Remove participants	`remove_participants`, `remove_participants_including_linked_groups`
Change admin roles	`promote_participants`, `demote_participants`
Inspect/decide pending membership	`get_membership_requests`, `approve_membership_requests`, `reject_membership_requests`
Cancel pending requests	`cancel_membership_requests`, `revoke_request_code`
Join or inspect an invite	`join_with_invite_code`, `join_with_invite_v4`, `get_invite_info`
Share an invite	`get_invite_link`
Leave	`leave`

Inspect per-participant results; a successful outer IQ does not make every member mutation successful. Server permissions still apply.

add_participants_with_history

The combined operation adds participants and shares eligible recent history. History sharing has its own outcomes after the participant mutation; it is not atomic with adding a member. For cancellation control, use prepare_group_history_share and deliver_prepared_history_share. Preparation establishes the replay handle; retain it across cancellation and call deliver_prepared_history_share again with the same prepared handle. Use retry_group_history only with the token returned by a retryable delivery outcome. Do not repeat the participant add merely to retry history. Read the source’s explicit selection, freshness and per-recipient constraints before constructing a custom flow.

Settings

Use typed modes and the source reference for exact arguments:

Access and roles: set_locked, set_announce, set_membership_approval, set_member_add_mode, set_member_link_mode, set_member_share_history_mode.
Retention and sharing: set_ephemeral, set_group_history, set_no_frequently_forwarded, set_limit_sharing.
Reporting: set_allow_admin_reports, report_messages_to_admins, get_reported_messages.
Member labels and state: update_member_label, update_member_label_with_id, acknowledge.

get_profile_pictures

get_profile_pictures(group_jids, PictureType) is a network batch with per-entry outcomes and a maximum of 1,000 groups. It remains distinct from a single-picture request. Inspect each GroupProfilePictureResult, including rejection metadata. Use the pictures facade for a single normal group or community parent. Group picture mutations remain set_profile_picture and remove_profile_picture.

Source reference

Facade, projections, history outcomes and DTO constructors · Core group inputs, typed modes and IQ contracts

GroupError

Group operations return their typed GroupError, preserving IQ, storage and validation causes. Description conflicts require reconciling current state before another update. Keep a fallback arm when matching this extensible enum. See the pinned error definition and error-chain recovery.

Durable notification capture

This API requires main snapshot 35a69a14. Register GroupNotificationDurabilityHook on ClientBuilder or BotBuilder using with_group_notification_durability_hook or its _arc variant. The last registration wins.

use std::sync::Arc;
use whatsapp_rust::{ClientBuilder, GroupNotificationDurabilityHook};

fn capture_groups(
    builder: ClientBuilder,
    capture: Arc<dyn GroupNotificationDurabilityHook>,
) -> ClientBuilder {
    builder.with_group_notification_durability_hook_arc(capture)
}

The callback is async fn on_notification(&self, node: Arc<OwnedNodeRef>) -> anyhow::Result<()>, with OwnedNodeRef from whatsapp_rust::OwnedNodeRef. It receives the complete notification type="w:gp2" envelope, including all actions, groups_dirty, and malformed or unknown group actions. The client awaits capture before stanza interceptors, group cache changes, sender-key rotation, typed group events and the transport ACK. An error suppresses these effects and ACK without sending an unknown-stanza NACK. Without the hook, processing keeps its existing behavior. Persist node.backing_bytes() verbatim and hash those exact bytes. They are unpacked decoded node bytes, not a network frame, JSON or a serialized GroupUpdate. Atomically persist the evidence and your downstream outbox before returning Ok(()). Scope an optional stanza ID by authenticated account/session and source group. A repeated ID with changed bytes requires conflict handling. Never invent an ID or use a default timestamp as identity. Without an ID, identical bytes cannot distinguish a redelivery from a distinct identical notification; record that ambiguity. Withholding ACK permits possible redelivery but does not guarantee it. A successful callback does not guarantee local effects or ACK if the connection retired meanwhile. Reconnect/shutdown can cancel capture; reconcile an indeterminate commit from persisted evidence before retrying. A metadata change already started can finish storage/cache publication and required sender-key rotation before later actions and ACK stop. A sender-key storage error needs reconciliation too. The SDK does not replay local effects or make event delivery durable. Drive downstream work from your outbox and deduplicate consumers. RawNode diagnostic observers can run before the gate. Captures for the same group share its inbound message lane; do not wait inside the callback for a later message or notification on that lane.

Core

Messaging

Features

Storage & Backends

Core Modules

Choose a projection

list_participating

fetch_metadata

routing_info

create_group

set_subject

set_description

Participants and membership

add_participants_with_history

Settings

get_profile_pictures

Source reference

GroupError

Durable notification capture

​Choose a projection

​list_participating

​fetch_metadata

​routing_info

​create_group

​set_subject

​set_description

​Participants and membership

​add_participants_with_history

​Settings

​get_profile_pictures

​Source reference

​GroupError

​Durable notification capture

Choose a projection

list_participating

fetch_metadata

routing_info

create_group

set_subject

set_description

Participants and membership

add_participants_with_history

Settings

get_profile_pictures

Source reference

GroupError

Durable notification capture