Community

The Community feature provides methods for managing WhatsApp communities, including creation, subgroup linking/unlinking, and metadata queries. Community mutations use IQ stanzas (w:g2 namespace) while metadata queries use MEX (GraphQL).

Access

Access community operations through the client:

let community = client.community();

Methods

create

Create a new community.

pub async fn create(
    &self,
    options: CreateCommunityOptions,
) -> Result<CreateCommunityResult, CommunityError>

Parameters:

options — Community creation options (see CreateCommunityOptions)

Returns:

CreateCommunityResult — Contains the full metadata: GroupMetadata for the created community parent group

Example:

use whatsapp_rust::features::community::CreateCommunityOptions;

let mut options = CreateCommunityOptions::new("My Community");
options.description = Some("A great community".to_string());
options.closed = true;

let result = client.community().create(options).await?;
println!("Created community: {} ({})", result.metadata.subject, result.metadata.id);
if let Some(desc) = &result.metadata.description {
    println!("Description: {}", desc);
}

Since v0.6, community().create() returns the full GroupMetadata instead of just the JID. The library inlines the community description directly into the create stanza (matching WA Web), so the returned metadata already contains it — no separate set_description round-trip is needed. If you previously read result.gid, switch to result.metadata.id (GroupMetadata uses id: Jid).

list_participating

List every parent community the account participates in as slim GroupOverview records. Same slim wire projection as Groups::list_participating: id, subject, hierarchy, and participant count — no subgroup members, no settings, one round trip.

pub async fn list_participating(
    &self,
) -> Result<Vec<GroupOverview>, CommunityError>

Returns:

Vec<GroupOverview> — one overview per parent community.

Example:

let communities = client.community().list_participating().await?;

for overview in communities {
    let subject = overview.subject.as_deref().unwrap_or("(no subject)");
    let count = overview.participant_count.unwrap_or(0);
    println!("Community: {subject} ({}) — {count} members", overview.id);
}

fetch_participating_metadata

Fetch full GroupMetadata for every parent community the account participates in.

pub async fn fetch_participating_metadata(
    &self,
) -> Result<HashMap<Jid, GroupMetadata>, CommunityError>

Returns:

HashMap<Jid, GroupMetadata> — Map of community JID to metadata.

Always hits the network. Returns protocol data only; call Groups::resolve_participant_addresses per result when PN-keyed display data is needed. Prefer list_participating when the display fields are all you need. Example:

let communities = client.community().fetch_participating_metadata().await?;

for (jid, metadata) in communities {
    let subject = metadata.subject.as_deref().unwrap_or("(no subject)");
    println!("Community: {subject} ({jid})");
}

deactivate

Deactivate (delete) a community. Subgroups are unlinked but not deleted.

pub async fn deactivate(&self, community_jid: &Jid) -> Result<(), CommunityError>

Parameters:

community_jid — JID of the community to deactivate

Example:

client.community().deactivate(&community_jid).await?;

link_subgroups

Link existing groups as subgroups of a community. All groups are linked with the default SubgroupVisibility::Visible; use link_subgroups_with_options to mix visible and hidden groups in a single request.

pub async fn link_subgroups(
    &self,
    community_jid: &Jid,
    subgroup_jids: &[Jid],
) -> Result<LinkSubgroupsResult, CommunityError>

Parameters:

community_jid — JID of the parent community
subgroup_jids — Array of group JIDs to link

Returns:

LinkSubgroupsResult — Contains linked_jids (successfully linked) and failed_groups (JID + error code pairs)

Example:

let subgroup_jids = vec![
    "120363001111111@g.us".parse()?,
    "120363002222222@g.us".parse()?,
];

let result = client.community()
    .link_subgroups(&community_jid, &subgroup_jids)
    .await?;

println!("Linked: {:?}", result.linked_jids);
for (jid, error_code) in &result.failed_groups {
    eprintln!("Failed: {} (error {})", jid, error_code);
}

link_subgroups_with_options

Link existing groups to a community with a per-group visibility. A single request can mix visible and hidden groups.

pub async fn link_subgroups_with_options(
    &self,
    community_jid: &Jid,
    subgroup_options: &[LinkSubgroupOptions],
) -> Result<LinkSubgroupsResult, CommunityError>

Parameters:

community_jid — JID of the parent community
subgroup_options — Array of per-group link options (see LinkSubgroupOptions)

Returns:

LinkSubgroupsResult — Same shape as link_subgroups.

Example:

use whatsapp_rust::features::community::{LinkSubgroupOptions, SubgroupVisibility};

let options = vec![
    LinkSubgroupOptions::new(
        "120363001111111@g.us".parse()?,
        SubgroupVisibility::Visible,
    ),
    LinkSubgroupOptions::new(
        "120363002222222@g.us".parse()?,
        SubgroupVisibility::Hidden,
    ),
];

let result = client.community()
    .link_subgroups_with_options(&community_jid, &options)
    .await?;

Visibility is set at link time. To change a group’s visibility later you must unlink and re-link it.

create_subgroup

Create a new group that is already linked as a subgroup of a community, in one call. The subgroup is created with the default SubgroupVisibility::Visible.

pub async fn create_subgroup(
    &self,
    name: &str,
    participants: &[Jid],
    parent_jid: &Jid,
) -> Result<CreateCommunityResult, CommunityError>

Parameters:

name — Name of the new subgroup
participants — Initial participant JIDs to add to the subgroup
parent_jid — JID of the parent community to link the new subgroup under

Returns:

CreateCommunityResult — Contains the full metadata: GroupMetadata for the created subgroup

Example:

let participants = vec![
    "5511999999999@s.whatsapp.net".parse()?,
];

let result = client.community()
    .create_subgroup("My Subgroup", &participants, &community_jid)
    .await?;

println!("Created subgroup: {} ({})", result.metadata.subject, result.metadata.id);

Equivalent to creating a group and then calling link_subgroups, but done in a single round-trip.

create_subgroup_with_options

Create a new subgroup linked to a community with an explicit visibility. Use this when the subgroup should be hidden from non-members in the community’s subgroup list.

pub async fn create_subgroup_with_options(
    &self,
    options: CreateSubgroupOptions,
) -> Result<CreateCommunityResult, CommunityError>

Parameters:

options — Subgroup creation options (see CreateSubgroupOptions)

Returns:

CreateCommunityResult — Contains the full metadata: GroupMetadata for the created subgroup

Example:

use whatsapp_rust::features::community::{CreateSubgroupOptions, SubgroupVisibility};

let participants = vec!["5511999999999@s.whatsapp.net".parse()?];

let options = CreateSubgroupOptions::new("Mods only", &participants, community_jid.clone())
    .with_visibility(SubgroupVisibility::Hidden);

let result = client.community()
    .create_subgroup_with_options(options)
    .await?;

Visibility is fixed at creation time. WhatsApp does not support changing a subgroup’s visibility later.

unlink_subgroups

Unlink subgroups from a community.

pub async fn unlink_subgroups(
    &self,
    community_jid: &Jid,
    subgroup_jids: &[Jid],
    remove_orphan_members: bool,
) -> Result<UnlinkSubgroupsResult, CommunityError>

Parameters:

community_jid — JID of the parent community
subgroup_jids — Array of subgroup JIDs to unlink
remove_orphan_members — Whether to remove members who are only in the community through the unlinked subgroups

Returns:

UnlinkSubgroupsResult — Contains unlinked_jids (successfully unlinked) and failed_groups (JID + error code pairs)

Example:

let result = client.community()
    .unlink_subgroups(&community_jid, &subgroup_jids, true)
    .await?;

println!("Unlinked: {:?}", result.unlinked_jids);

get_subgroups

Fetch all subgroups of a community via MEX (GraphQL).

pub async fn get_subgroups(
    &self,
    community_jid: &Jid,
) -> Result<Vec<CommunitySubgroup>, CommunityError>

Parameters:

community_jid — JID of the community

Returns:

Vec<CommunitySubgroup> — List of subgroups with metadata

Example:

let subgroups = client.community()
    .get_subgroups(&community_jid)
    .await?;

for sg in &subgroups {
    println!("{}: {} (default: {}, general: {}, hidden: {})",
        sg.id, sg.subject, sg.is_default_sub_group, sg.is_general_chat, sg.is_hidden_group);
}

get_subgroup_participant_counts

Fetch participant counts per subgroup via MEX (GraphQL).

pub async fn get_subgroup_participant_counts(
    &self,
    community_jid: &Jid,
) -> Result<Vec<(Jid, u32)>, CommunityError>

Parameters:

community_jid — JID of the community

Returns:

Vec<(Jid, u32)> — Pairs of subgroup JID and participant count

Example:

let counts = client.community()
    .get_subgroup_participant_counts(&community_jid)
    .await?;

for (jid, count) in &counts {
    println!("{}: {} participants", jid, count);
}

query_linked_group

Query a linked subgroup’s metadata from the parent community.

pub async fn query_linked_group(
    &self,
    community_jid: &Jid,
    subgroup_jid: &Jid,
) -> Result<GroupMetadata, CommunityError>

Parameters:

community_jid — JID of the parent community
subgroup_jid — JID of the subgroup to query

Returns:

GroupMetadata — Full group metadata (see Groups API)

Example:

let metadata = client.community()
    .query_linked_group(&community_jid, &subgroup_jid)
    .await?;

println!("Subject: {}", metadata.subject);

join_subgroup

Join a linked subgroup via the parent community.

pub async fn join_subgroup(
    &self,
    community_jid: &Jid,
    subgroup_jid: &Jid,
) -> Result<GroupMetadata, CommunityError>

Parameters:

community_jid — JID of the parent community
subgroup_jid — JID of the subgroup to join

Returns:

GroupMetadata — Metadata of the joined subgroup

Example:

let metadata = client.community()
    .join_subgroup(&community_jid, &subgroup_jid)
    .await?;

println!("Joined: {}", metadata.subject);

get_linked_groups_participants

Get all participants across all linked groups of a community.

pub async fn get_linked_groups_participants(
    &self,
    community_jid: &Jid,
) -> Result<Vec<GroupParticipant>, CommunityError>

Parameters:

community_jid — JID of the community

Returns:

Vec<GroupParticipant> — List of participants across all subgroups

Example:

let participants = client.community()
    .get_linked_groups_participants(&community_jid)
    .await?;

for p in &participants {
    println!("{} (admin: {})", p.jid, p.is_admin);
}

remove_participants

Remove participants from a community.

pub async fn remove_participants(
    &self,
    community_jid: &Jid,
    participants: &[Jid],
) -> Result<Vec<ParticipantChangeResponse>, CommunityError>

Parameters:

community_jid — JID of the community
participants — Array of participant JIDs to remove

Returns:

Vec<ParticipantChangeResponse> — Result for each participant (see ParticipantChangeResponse)

Example:

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

let results = client.community()
    .remove_participants(&community_jid, &to_remove)
    .await?;

for result in results {
    println!("{}: status {:?}", result.jid, result.status);
}

Types

CreateCommunityOptions

Options for creating a new community. Implements PartialEq and Eq.

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CreateCommunityOptions {
    pub name: String,
    pub description: Option<String>,
    pub closed: bool,
    pub allow_non_admin_sub_group_creation: bool,
    pub create_general_chat: bool,
}

Fields:

name — Community name
description — Optional description. Since v0.6 it’s inlined as a <description> child of the create stanza, so the community is created with the description in a single round-trip (no follow-up set_description IQ needed).
closed — Whether the community requires approval to join (default: false)
allow_non_admin_sub_group_creation — Whether non-admin members can create subgroups (default: false)
create_general_chat — Whether to create a general chat subgroup (default: true)

Constructor:

let options = CreateCommunityOptions::new("My Community");

CreateCommunityResult

Result of creating a community.

#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct CreateCommunityResult {
    pub metadata: GroupMetadata,
}

The metadata field carries the full community parent metadata from the server, with the inline description: Option<String> already populated. See GroupMetadata for the full field list. CreateCommunityResult is #[non_exhaustive]: struct-literal construction and exhaustive struct destructuring from outside the crate are both disallowed. Field reads are unaffected; add .. to any exhaustive destructuring patterns.

Prior to v0.6 this struct exposed only gid: Jid and derived PartialEq, Eq. The Eq derives were dropped because GroupMetadata does not implement them.

CommunitySubgroup

A subgroup within a community. Implements PartialEq and Eq.

#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct CommunitySubgroup {
    pub id: Jid,
    pub subject: String,
    pub participant_count: Option<u32>,
    pub creation: Option<u64>,
    pub owner: Option<Jid>,
    pub is_default_sub_group: bool,
    pub is_general_chat: bool,
    pub is_hidden_group: bool,
}

CommunitySubgroup is #[non_exhaustive]: struct-literal construction and exhaustive struct destructuring from outside the crate are both disallowed. Field reads are unaffected; add .. to any exhaustive destructuring patterns. Fields:

id — Subgroup JID
subject — Subgroup name
participant_count — Number of participants (if available)
creation — Subgroup creation timestamp (Unix seconds), if available
owner — JID of the subgroup owner, if available
is_default_sub_group — Whether this is the default announcement subgroup
is_general_chat — Whether this is the general chat subgroup
is_hidden_group — Whether this subgroup is hidden from non-members in the community’s subgroup list. Reflects the hidden_group property parsed from the MEX response; defaults to false if the server omits it.

SubgroupVisibility

Visibility selected when a subgroup is created or linked. Implements Copy, PartialEq, Eq, and Default (Visible).

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[non_exhaustive]
pub enum SubgroupVisibility {
    #[default]
    Visible,
    Hidden,
}

Variants:

Visible — The subgroup appears in the community’s subgroup list.
Hidden — The subgroup is omitted from the community’s subgroup list for users who are not members. Visibility cannot be changed after linking.

CreateSubgroupOptions

Options passed to create_subgroup_with_options when creating a subgroup already linked to a community.

#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct CreateSubgroupOptions {
    pub name: String,
    pub participants: Vec<Jid>,
    pub parent_jid: Jid,
    pub visibility: SubgroupVisibility,
}

Fields:

name — Name of the new subgroup
participants — Initial participant JIDs to add to the subgroup
parent_jid — JID of the parent community to link the new subgroup under
visibility — Visibility applied at creation time (defaults to Visible)

Constructors:

// Visible-by-default options
let options = CreateSubgroupOptions::new("Announcements", &participants, community_jid.clone());

// Override the visibility
let hidden = options.with_visibility(SubgroupVisibility::Hidden);

LinkSubgroupOptions

Options for linking a single existing group to a community via link_subgroups_with_options.

#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct LinkSubgroupOptions {
    pub jid: Jid,
    pub visibility: SubgroupVisibility,
}

Fields:

jid — JID of the existing group to link
visibility — Visibility applied to this group at link time

Constructor:

let opt = LinkSubgroupOptions::new(group_jid, SubgroupVisibility::Hidden);

LinkSubgroupsResult

Result of linking subgroups to a community. Implements PartialEq and Eq.

#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct LinkSubgroupsResult {
    pub linked_jids: Vec<Jid>,
    pub failed_groups: Vec<(Jid, u32)>,
}

LinkSubgroupsResult is #[non_exhaustive]: struct-literal construction and exhaustive struct destructuring from outside the crate are both disallowed. Field reads are unaffected; add .. to any exhaustive destructuring patterns.

UnlinkSubgroupsResult

Result of unlinking subgroups from a community. Implements PartialEq and Eq.

#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct UnlinkSubgroupsResult {
    pub unlinked_jids: Vec<Jid>,
    pub failed_groups: Vec<(Jid, u32)>,
}

UnlinkSubgroupsResult is #[non_exhaustive]: struct-literal construction and exhaustive struct destructuring from outside the crate are both disallowed. Field reads are unaffected; add .. to any exhaustive destructuring patterns.

GroupType

Classification of a group within the community hierarchy. Implements PartialEq and Eq.

#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum GroupType {
    Default,
    Community,
    LinkedSubgroup,
    LinkedAnnouncementGroup,
    LinkedGeneralGroup,
}

GroupType is #[non_exhaustive], so match statements should include a wildcard arm to handle future variants. Variants:

Default — Regular standalone group
Community — Community parent group
LinkedSubgroup — A subgroup linked to a community
LinkedAnnouncementGroup — The default announcement subgroup of a community
LinkedGeneralGroup — The general chat subgroup of a community

Use the group_type() function to classify a group:

use whatsapp_rust::features::community::{group_type, GroupType};

let metadata = client.groups().fetch_metadata(&group_jid).await?;
let gtype = group_type(&metadata);

Error handling

All community methods return Result<T, CommunityError>:

#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum CommunityError {
    #[error("{0}")]
    Iq(#[from] IqError),
    #[error("{0}")]
    Mex(#[from] MexError),
    #[error("{0}")]
    Group(#[from] GroupError),
    #[error("invalid community request: {0}")]
    InvalidRequest(String),
}

use whatsapp_rust::CommunityError;

match client.community().deactivate(&community_jid).await {
    Ok(_) => println!("Community deactivated"),
    Err(CommunityError::Iq(e)) => eprintln!("Server error: {}", e),
    Err(CommunityError::Mex(e)) => eprintln!("MEX error: {}", e),
    Err(e) => eprintln!("Error: {}", e),
}

Core

Messaging

Features

Storage & Backends

Core Modules

Access

Methods

create

list_participating

fetch_participating_metadata

deactivate

link_subgroups

link_subgroups_with_options

create_subgroup

create_subgroup_with_options

unlink_subgroups

get_subgroups

get_subgroup_participant_counts

query_linked_group

join_subgroup

get_linked_groups_participants

remove_participants

Types

CreateCommunityOptions

CreateCommunityResult

CommunitySubgroup

SubgroupVisibility

CreateSubgroupOptions

LinkSubgroupOptions

LinkSubgroupsResult

UnlinkSubgroupsResult

GroupType

Error handling

​Access

​Methods

​create

​list_participating

​fetch_participating_metadata

​deactivate

​link_subgroups

​link_subgroups_with_options

​create_subgroup

​create_subgroup_with_options

​unlink_subgroups

​get_subgroups

​get_subgroup_participant_counts

​query_linked_group

​join_subgroup

​get_linked_groups_participants

​remove_participants

​Types

​CreateCommunityOptions

​CreateCommunityResult

​CommunitySubgroup

​SubgroupVisibility

​CreateSubgroupOptions

​LinkSubgroupOptions

​LinkSubgroupsResult

​UnlinkSubgroupsResult

​GroupType

​Error handling

Access

Methods

create

list_participating

fetch_participating_metadata

deactivate

link_subgroups

link_subgroups_with_options

create_subgroup

create_subgroup_with_options

unlink_subgroups

get_subgroups

get_subgroup_participant_counts

query_linked_group

join_subgroup

get_linked_groups_participants

remove_participants

Types

CreateCommunityOptions

CreateCommunityResult

CommunitySubgroup

SubgroupVisibility

CreateSubgroupOptions

LinkSubgroupOptions

LinkSubgroupsResult

UnlinkSubgroupsResult

GroupType

Error handling