Groups struct provides methods for managing WhatsApp groups, including creating groups, managing participants, and modifying group settings.
Access
Access group operations through the client:Methods
query_info
Query group information with caching support.jid- Group JID (must end with@g.us)
Arc<GroupInfo>- Shared, reference-counted snapshot containing the participants list and addressing mode. Repeated calls for the same group return the sameArcfrom the in-memory cache, so warm sends avoid deep-cloning group metadata.
get_participating
Get all groups the client is participating in.HashMap<Jid, GroupMetadata>- Map of groupJidto metadata
This map is keyed by
Jid. Call .to_string() on the key if you need the string form.GroupMetadata implements PartialEq and Eq, allowing direct comparison of group metadata instances.
GroupMetadata fields:
id: Jid- Group JIDsubject: String- Group nameparticipants: Vec<GroupParticipant>- List of participantsaddressing_mode: AddressingMode- Phone number or LID modecreator: Option<Jid>- Group creator JIDcreation_time: Option<u64>- Group creation timestamp (Unix seconds)subject_time: Option<u64>- Subject modification timestamp (Unix seconds)subject_owner: Option<Jid>- Subject owner JIDdescription: Option<String>- Group description body textdescription_id: Option<String>- Description ID (for conflict detection)description_owner: Option<Jid>- JID of the participant who set the descriptiondescription_time: Option<u64>- Timestamp when the description was set (Unix seconds)is_locked: bool- Whether only admins can edit group infois_announcement: bool- Whether only admins can send messagesephemeral_expiration: u32- Disappearing messages timer in seconds (0 = disabled)ephemeral_trigger: Option<u32>- Disappearing mode trigger value (from thetriggerattribute on<ephemeral>)membership_approval: bool- Whether admin approval is required to joinmember_add_mode: Option<MemberAddMode>- Who can add membersmember_link_mode: Option<MemberLinkMode>- Who can use invite linkssize: Option<u32>- Total participant countis_parent_group: bool- Whether this group is a community parent groupparent_group_jid: Option<Jid>- JID of the parent community (for subgroups)is_default_sub_group: bool- Whether this is the default announcement subgroup of a communityis_general_chat: bool- Whether this is the general chat subgroup of a communityallow_non_admin_sub_group_creation: bool- Whether non-admin community members can create subgroupsno_frequently_forwarded: bool- Whether frequently-forwarded messages are restrictedmember_share_history_mode: Option<MemberShareHistoryMode>- Who can share message history with new membersgrowth_locked: Option<GrowthLockInfo>- Growth lock status (invite links temporarily disabled by the system)is_suspended: bool- Whether the group is suspendedallow_admin_reports: bool- Whether admin reports are allowedis_hidden_group: bool- Whether the group is hiddenis_incognito: bool- Whether incognito mode is enabledhas_group_history: bool- Whether group history is enabledis_limit_sharing_enabled: bool- Whether limit sharing is enabled
GroupParticipant implements PartialEq and Eq.
GroupParticipant fields:
jid: Jid- Participant JIDphone_number: Option<Jid>- Phone number JID (for LID groups)participant_type: ParticipantType- Participant role (member, admin, or super admin)
get_metadata
Get metadata for a specific group.jid- Group JID
GroupMetadata- Group metadata (seeget_participatingfor fields)
create_group
Create a new group.options: GroupCreateOptions- Group creation optionssubject: String- Group name (max 100 characters)participants: Vec<GroupParticipantOptions>- Initial participantsmember_link_mode: Option<MemberLinkMode>- Who can use invite links (default:AdminLink)member_add_mode: Option<MemberAddMode>- Who can add members (default:AllMemberAdd)membership_approval_mode: Option<MembershipApprovalMode>- Require admin approval (default:Off)ephemeral_expiration: Option<u32>- Disappearing messages timer in seconds (default:0)is_parent: bool- Create as a community parent group (default:false)closed: bool- Whether the community requires approval to join. Only used whenis_parentistrue(default:false)allow_non_admin_sub_group_creation: bool- Allow non-admin members to create subgroups. Only used whenis_parentistrue(default:false)create_general_chat: bool- Create a general chat subgroup alongside the community. Only used whenis_parentistrue(default:false)linked_parent: Option<Jid>- Atomically link this group as a subgroup of an existing community on create. Mutually exclusive withis_parent— when set, the new group is always classified as a subgroup even ifis_parent: trueis also passed. (added in v0.6)description: Option<String>- Inline group description, emitted as a<description>child of the<create>stanza so it lands in one round-trip. Matches the existing community-create behavior. (added in v0.6)
CreateGroupResultwith ametadata: GroupMetadatafield carrying the full server response (JID, subject, addressing mode, participants with display names, parent/community linkage, etc.).
PRIVACY_TOKEN_ON_GROUP_CREATE AB prop is enabled, the library automatically resolves and attaches privacy tokens (tc_token) to each participant during group creation. This is handled internally — you don’t need to manage tokens yourself.
Example:
Since v0.6,
create_group returns the full GroupMetadata (matching get_metadata) instead of just the JID. Inspect result.metadata for participants, addressing mode, ephemeral timer, and parent linkage in a single round-trip. GroupMetadata.participants is a Vec<GroupParticipant> (the IQ-response shape), not the GroupParticipantInfo used by group notification events — so masked-number display_name labels are only available on the event-side GroupParticipantInfo, not here.set_subject
Change the group name.jid- Group JIDsubject- New group name (max 100 characters)
set_description
Set or delete the group description.jid- Group JIDdescription- New description (max 2048 characters) orNoneto deleteprev- Current description ID for conflict detection, borrowed asOption<&str>(passNoneif unknown)
prev borrows the id (Option<&str>). Pass Some("PREV_ID") or None.leave
Leave a group.jid- Group JID to leave
add_participants
Add participants to a group.jid- Group JIDparticipants- Array of participant JIDs to add
Vec<ParticipantChangeResponse>- Result for each participant
PRIVACY_TOKEN_ON_GROUP_PARTICIPANT_ADD AB prop is enabled, the library automatically resolves and attaches privacy tokens (tc_token) to each participant. This is handled internally — you don’t need to manage tokens yourself.
Example:
remove_participants
Remove participants from a group.jid- Group JIDparticipants- Array of participant JIDs to remove
Vec<ParticipantChangeResponse>- Result for each participant
promote_participants
Promote participants to admin.jid- Group JIDparticipants- Array of participant JIDs to promote
demote_participants
Demote admin participants to regular members.jid- Group JIDparticipants- Array of admin JIDs to demote
get_invite_link
Get or reset the group invite link.jid- Group JIDreset- Whether to reset and generate a new invite link
String- Invite link code
join_with_invite_code
Join a group using an invite code or full invite URL.code- Invite code or full URL (e.g.,"AbCdEfGh"or"https://chat.whatsapp.com/AbCdEfGh")
JoinGroupResult- EitherJoined(Jid)if immediately joined, orPendingApproval(Jid)if the group requires admin approval
join_with_invite_v4
Accept a V4 group invite received as aGroupInviteMessage (not a link). V4 invites are sent directly by a group admin as a message, rather than shared as a URL.
group_jid- The target group JIDcode- Invite code from theGroupInviteMessageexpiration- Invite expiration timestamp (Unix seconds). The method returns an error if the invite has expired.admin_jid- JID of the admin who sent the invite
JoinGroupResult- EitherJoined(Jid)if immediately joined, orPendingApproval(Jid)if the group requires admin approval
V4 invites expire. The method automatically checks the expiration timestamp and returns an error if the invite has already expired. You can pass
0 as the expiration to skip the expiration check.get_invite_info
Get group metadata from an invite code without joining the group.code- Invite code or full URL
GroupMetadata- Group metadata (seeget_participatingfor fields)
set_locked
Lock or unlock the group so only admins can change group info.jid- Group JIDlocked-trueto lock (only admins edit info),falseto unlock
set_announce
Set announcement mode. When enabled, only admins can send messages.jid- Group JIDannounce-trueto enable (only admins send),falseto disable
set_ephemeral
Set the disappearing messages timer on the group.jid- Group JIDexpiration- Timer duration in seconds. Common values:86400(24 hours),604800(7 days),7776000(90 days). Pass0to disable.
set_membership_approval
Set membership approval mode. When enabled, new members must be approved by an admin.jid- Group JIDmode-MembershipApprovalMode::Onto require approval,MembershipApprovalMode::Offto disable
get_membership_requests
Get pending membership approval requests for a group.jid- Group JID
Vec<MembershipRequest>- List of pending requests
approve_membership_requests
Approve pending membership requests for a group.jid- Group JIDparticipants- Array of JIDs to approve
Vec<ParticipantChangeResponse>- Result for each participant
reject_membership_requests
Reject pending membership requests for a group.jid- Group JIDparticipants- Array of JIDs to reject
Vec<ParticipantChangeResponse>- Result for each participant
set_member_add_mode
Set who can add members to the group.jid- Group JIDmode-MemberAddMode::AdminAddto restrict to admins,MemberAddMode::AllMemberAddto allow all members
set_no_frequently_forwarded
Restrict or allow frequently-forwarded messages in the group.jid- Group JIDrestrict-trueto restrict frequently-forwarded messages,falseto allow them
set_allow_admin_reports
Enable or disable admin reports in the group.jid- Group JIDallow-trueto enable admin reports,falseto disable
set_group_history
Enable or disable group history sharing.jid- Group JIDenabled-trueto enable group history,falseto disable
set_member_link_mode
Set who can share invite links. This uses the MEX (Mutation Exchange) protocol.jid- Group JIDmode-MemberLinkMode::AdminLinkto restrict to admins,MemberLinkMode::AllMemberLinkto allow all members
set_member_share_history_mode
Set who can share message history with new members. This uses the MEX protocol.jid- Group JIDmode-MemberShareHistoryMode::AdminShareto restrict to admins,MemberShareHistoryMode::AllMemberShareto allow all members
set_limit_sharing
Enable or disable limit sharing in the group. This uses the MEX protocol.jid- Group JIDenabled-trueto enable limit sharing,falseto disable
cancel_membership_requests
Cancel pending membership requests from the requesting user’s side.jid- Group JIDparticipants- Array of JIDs whose pending requests to cancel
Vec<ParticipantChangeResponse>- Result for each participant
revoke_request_code
Revoke invitation codes from specific participants. This is an admin operation.jid- Group JIDparticipants- Array of participant JIDs whose invitation codes to revoke
Vec<ParticipantChangeResponse>- Result for each participant
acknowledge
Acknowledge a group notification.jid- Group JID
batch_get_info
Batch query group info for multiple groups at once.jids- List of group JIDs to query (max 10,000)
Vec<BatchGroupResult>- Result for each group
set_profile_picture
Set a group’s profile picture. Admin operation.group_jid- Group JID (must end with@g.us)image_data- JPEG image bytes. The caller is responsible for sizing/cropping the image (WhatsApp uses 640x640).
SetProfilePictureResponse- Contains the new picture ID
image_data routes to removal, mirroring the own-picture API. Prefer remove_profile_picture when removal is the intent.
Example:
remove_profile_picture
Remove a group’s profile picture. Admin operation.group_jid- Group JID
SetProfilePictureResponse- Confirmation of removal
SetProfilePictureResponse for the response shape.
get_profile_pictures
Batch fetch group profile pictures.group_jids- List of group JIDs (max 1,000)picture_type-PictureType::Previewfor thumbnails orPictureType::Imagefor full-size
Vec<GroupProfilePicture>- Profile picture data for each group
Types
GroupInfo
Cached group information returned byquery_info. Contains participant list, addressing mode, and LID-to-phone mappings for privacy-addressed groups.
query_info returns Arc<GroupInfo> so that repeated lookups and warm sends share the same snapshot without deep-cloning the participants list.
Example:
GroupSubject
Validated group name with 100 character limit.GroupDescription
Validated group description with 2048 character limit.MemberAddMode
ParticipantType
Participant role within a group.is_admin(&self) -> bool- Returnstrueif admin or super admin
MemberLinkMode
Controls who can use invite links to join the group.MemberShareHistoryMode
Controls who can share message history with new members.MembershipApprovalMode
GroupParticipantOptions
Options for specifying a participant when creating or modifying a group.GroupParticipantOptions::new(jid)- Create from a JIDGroupParticipantOptions::from_phone(phone_number)- Create from a phone number JIDGroupParticipantOptions::from_lid_and_phone(lid, phone_number)- Create from a LID and phone number
.with_phone_number(jid)- Attach a phone number JID (for LID participants).with_privacy(token)- Attach a privacy token (tc_tokenbytes)
You typically don’t need to set the
privacy field manually. When AB props are enabled, the library automatically resolves and attaches privacy tokens during create_group and add_participants operations.JoinGroupResult
Result of joining a group via invite code.group_jid(&self) -> &Jid- Returns the group JID regardless of result variant
MembershipRequest
A pending membership approval request.ParticipantChangeResponse
Result of a participant change operation (add, remove, approve, reject).ParticipantChangeResponse is #[non_exhaustive]. Field reads are unaffected; only exhaustive struct destructuring from outside the crate requires adding ...add_request is populated when the server responds with HTTP 403 carrying an <add_request> child — that happens when a participant has privacy blocked direct adds and the inviter must send them a v4 invite link out-of-band. Since v0.6 the value is preserved instead of being dropped, so consumers can drive the v4 invite flow without parsing the raw IQ.
AddressingMode
BatchGroupResult
Result for a single group in a batch query.GrowthLockInfo
Growth lock information (system-managed, read-only). When present, invite links are temporarily disabled by the system.PictureType
Profile picture query type for batch fetching.GroupProfilePicture
A single group profile picture result from a batch query.CreateGroupResult
Result of creating a group.CreateGroupResult is #[non_exhaustive]. Field reads are unaffected; only exhaustive struct destructuring from outside the crate requires adding ...metadata field carries the full group state returned by the server (same shape as get_metadata). metadata.participants is Vec<GroupParticipant> — note that masked-number display_name labels live on GroupParticipantInfo (which carries <participant> children of notification events), not on GroupParticipant here.
Prior to v0.6 this struct only exposed a
gid: Jid. Replace result.gid with result.metadata.id when upgrading (GroupMetadata.id, not jid). The same migration applies to CreateCommunityResult.GroupJoinError
Error codes returned when joining a group via invite fails.from_code(code: u16) -> Self- Create from a numeric status codecode(&self) -> u16- Get the numeric status code
InviteInfoError
Error codes returned when fetching group info from an invite code.from_code(code: u16) -> Self- Create from a numeric status codecode(&self) -> u16- Get the numeric status code
Error types
GroupError
All group methods return Result<T, GroupError>:
Iq— IQ request failed (timeout, server rejection, etc.)Mex— MEX protocol error (for methods using the MEX transport)InvalidRequest— malformed request (expired invite, missing fields, etc.)Internal— catch-all for other errors