Group Management
Relevant source files
The following files were used as context for generating this wiki page:
The Group Management system in Baileys provides a robust framework for interacting with WhatsApp groups and communities. It encompasses features for group creation, participant modification, metadata retrieval, and administrative settings. The system is built on top of the underlying socket architecture, utilizing binary nodes to communicate with WhatsApp servers.
This module handles two primary types of collective entities: standard groups (G2) and communities. While they share similar logic for participant management and metadata extraction, communities include additional layers for managing linked sub-groups and parent-child relationships. Sources: lib/Socket/groups.js, lib/Socket/community.js
Architecture and Components
The group management logic is encapsulated within the makeGroupsSocket factory function, which extends the base chat socket capabilities. It relies heavily on the w:g2 XML namespace for Information Query (IQ) stanzas.
Core Architecture Flow
The following diagram illustrates how the socket handles group-related queries and updates.
The system uses a centralized groupQuery function to wrap all IQ requests sent to the WhatsApp servers. Sources: lib/Socket/groups.js:13-21
Group Operations
Creation and Participation
Groups are created by specifying a subject and an initial list of participant JIDs. The groupCreate function generates a unique message ID as a key for the creation stanza.
| Function | Parameters | Return Type | Description |
|---|---|---|---|
groupCreate | subject: string, participants: string[] | Promise<GroupMetadata> | Creates a new group and returns its metadata. |
groupLeave | id: string | Promise<void> | Removes the current user from the specified group. |
groupFetchAllParticipating | None | Promise<{[id: string]: GroupMetadata}> | Retrieves metadata for all groups the user is currently in. |
Sources: lib/Socket/groups.js:62-92, lib/Socket/groups.d.ts:9-12
Participant Management
Participant updates involve actions such as adding, removing, promoting, or demoting members. These actions are governed by the ParticipantAction type.
Metadata and Data Structures
GroupMetadata Schema
The GroupMetadata interface represents the state of a group, including its administrative settings and participant list.
| Field | Type | Description |
|---|---|---|
id | string | The JID of the group (e.g., 12345@g.us). |
owner | string | JID of the group creator. |
subject | string | The display name of the group. |
participants | GroupParticipant[] | Array of members and their admin status. |
restrict | boolean | If true, only admins can change settings. |
announce | boolean | If true, only admins can send messages. |
joinApprovalMode | boolean | If true, joining requires admin approval. |
Sources: lib/Types/GroupMetadata.d.ts:15-56
Metadata Extraction
The extractGroupMetadata utility parses the binary node response from the server into the structured GroupMetadata object. It handles complex fields like addressing modes (LID vs PN) and ephemeral message durations. Sources: lib/Socket/groups.js:203-263
Community Management
Communities function as wrappers for multiple groups. The makeCommunitiesSocket adds specialized logic for handling the parent-child group hierarchy.
Community Structure
Communities support unique operations like communityRequestParticipantsList to manage membership approval requests and communityMemberAddMode to define who can add members. Sources: lib/Socket/community.js:105-115, lib/Socket/community.d.ts:25-30
Group Notifications
The system processes incoming server notifications to keep the local state synchronized. When a group property changes (e.g., subject change, participant add), the messages-recv module decodes the w:gp2 notification.
Notification Handling Logic
The handleGroupNotification function maps server tags to WAMessageStubType values:
subject:GROUP_CHANGE_SUBJECTdescription:GROUP_CHANGE_DESCRIPTIONpromote/demote:GROUP_PARTICIPANT_PROMOTE/DEMOTEmembership_approval_mode:GROUP_MEMBERSHIP_JOIN_APPROVAL_MODE
Sources: lib/Socket/messages-recv.js:464-585
Settings and Privacy
Admins can toggle various group settings through the groupSettingUpdate and groupMemberAddMode functions.
// Example: Lock settings to admins only
await sock.groupSettingUpdate('jid@g.us', 'locked')
// Example: Allow everyone to add members
await sock.groupMemberAddMode('jid@g.us', 'all_member_add')
Sources: lib/Socket/groups.js:192-197, lib/Socket/groups.d.ts:31-33
Summary
The Group Management module provides a comprehensive API for interacting with the WhatsApp group ecosystem. By abstracting the complexity of binary nodes and binary protocol namespaces into high-level JavaScript functions, it allows developers to manage group lifecycles, administrative controls, and community structures efficiently. The inclusion of metadata extraction for both standard and LID-based addressing ensures compatibility across different WhatsApp account types.