WPP.group — Group creation and management API reference

The WPP.group module wraps WhatsApp Web’s group management internals. Group IDs use the @g.us suffix (e.g. 120363000000000001@g.us), while participant IDs use @c.us. All async functions return Promises and should be awaited. Many participant-accepting functions take either a single ID string or an array of strings.

You must be a group admin to perform most write operations (add/remove/promote/demote participants, change settings). The iAmAdmin function lets you check your role before attempting privileged actions.

Creating, joining, and leaving groups

`WPP.group.create(groupName, participantsIds, parentGroup?)`

Creates a new group and returns its ID together with per-participant result codes.

create(
  groupName: string,
  participantsIds: (string | Wid) | (string | Wid)[],
  parentGroup?: string | Wid
): Promise<{
  gid: Wid;
  participants: {
    [key: `${number}@c.us`]: {
      wid: string;
      code: number;
      invite_code: string | null;
      invite_code_exp: number | null;
    };
  };
}>

groupName

string

required

The display name (subject) for the new group.

participantsIds

string | string[]

required

One or more @c.us WIDs to add at creation time.

parentGroup

string | Wid

Pass a community’s @g.us WID to create the group as a linked subgroup inside that community.

// Basic group creation
const result = await WPP.group.create('My Group', ['15550001234@c.us']);
console.log('Group ID:', result.gid.toString());

// Check per-participant result
const member = result['15550001234@c.us'];
console.log('Code:', member.code);       // 200 = added, 403 = restricted, 409 = already member
if (member.invite_code) {
  const link = 'https://chat.whatsapp.com/' + member.invite_code;
  console.log('Invite link to send:', link);
}

// Create a subgroup inside a community
const sub = await WPP.group.create('Subgroup', ['15550001234@c.us'], '120363000000000001@g.us');

When a participant’s code is 403, WhatsApp generated a private invite link in invite_code. Send that link to the user so they can join voluntarily.

`WPP.group.join(inviteCode)`

Joins a group using an invite code or a full invite URL. The function strips common URL prefixes automatically.

join(inviteCode: string): Promise<{ id: string }>

inviteCode

string

required

The invite code (e.g. AbCdEf123456) or a full URL (https://chat.whatsapp.com/AbCdEf123456).

// Code only
const result = await WPP.group.join('AbCdEf123456');
console.log('Joined group:', result.id);

// Full URL also works
await WPP.group.join('https://chat.whatsapp.com/AbCdEf123456');

`WPP.group.leave(groupId)`

Leaves a group.

leave(groupId: string | Wid): Promise<void>

groupId

string | Wid

required

The @g.us WID of the group to leave.

await WPP.group.leave('120363000000000001@g.us');

Managing participants

`WPP.group.addParticipants(groupId, participantsIds)`

Adds one or more participants to a group. Returns a per-participant result map.

addParticipants(
  groupId: string | Wid,
  participantsIds: (string | Wid) | (string | Wid)[]
): Promise<{
  [key: `${number}@c.us`]: {
    wid: string;
    code: number;
    message: string;
    invite_code: string | null;
    invite_code_exp: number | null;
  };
}>

groupId

string | Wid

required

The @g.us WID of the target group.

participantsIds

string | string[]

required

One or more @c.us WIDs to add.

Response codes per participant:

Code	Meaning
`200`	Added successfully
`403`	Contact restricted this group from adding them
`409`	Contact is already a member
`421`	Awaiting admin approval (join requests enabled)

const result = await WPP.group.addParticipants(
  '120363000000000001@g.us',
  ['15550001234@c.us', '15550005678@c.us']
);

for (const [wid, info] of Object.entries(result)) {
  console.log(wid, '->', info.code, info.message);
}

`WPP.group.removeParticipants(groupId, participantsIds)`

Removes one or more participants from a group.

removeParticipants(
  groupId: string | Wid,
  participantsIds: (string | Wid) | (string | Wid)[]
): Promise<void>

groupId

string | Wid

required

The @g.us WID of the group.

participantsIds

string | string[]

required

One or more @c.us WIDs to remove.

// Remove one
await WPP.group.removeParticipants('120363000000000001@g.us', '15550001234@c.us');

// Remove multiple
await WPP.group.removeParticipants('120363000000000001@g.us', [
  '15550001234@c.us',
  '15550005678@c.us',
]);

`WPP.group.getParticipants(groupId)`

Returns all current group participants as an array of ParticipantModel objects.

getParticipants(groupId: string | Wid): Promise<ParticipantModel[]>

groupId

string | Wid

required

The @g.us WID of the group.

const participants = await WPP.group.getParticipants('120363000000000001@g.us');
participants.forEach(p => {
  console.log(p.id.toString(), 'isAdmin:', p.isAdmin, 'isSuperAdmin:', p.isSuperAdmin);
});

`WPP.group.getPastParticipants(groupId)`

Returns participants who have previously left or been removed from the group.

getPastParticipants(groupId: string | Wid): Promise<ParticipantModel[]>

groupId

string | Wid

required

The @g.us WID of the group.

const past = await WPP.group.getPastParticipants('120363000000000001@g.us');
console.log('Former members:', past.length);

Admin roles

`WPP.group.promoteParticipants(groupId, participantsIds)`

Promotes one or more participants to group admin. Throws if any participant is already an admin.

promoteParticipants(
  groupId: string | Wid,
  participantsIds: (string | Wid) | (string | Wid)[]
): Promise<void>

groupId

string | Wid

required

The @g.us WID of the group.

participantsIds

string | string[]

required

One or more @c.us WIDs to promote.

await WPP.group.promoteParticipants('120363000000000001@g.us', '15550001234@c.us');

`WPP.group.demoteParticipants(groupId, participantsIds)`

Removes admin status from one or more participants. Throws if any participant is not currently an admin.

demoteParticipants(
  groupId: string | Wid,
  participantsIds: (string | Wid) | (string | Wid)[]
): Promise<void>

groupId

string | Wid

required

The @g.us WID of the group.

participantsIds

string | string[]

required

One or more @c.us WIDs to demote.

await WPP.group.demoteParticipants('120363000000000001@g.us', '15550001234@c.us');

Permission checks

These functions check whether the current account has permission to perform specific actions in a group. They all return a boolean.

`WPP.group.canAdd(groupId)`

Checks if the current account is allowed to add new participants.

canAdd(groupId: string | Wid): Promise<boolean>

`WPP.group.canPromote(groupId, participantsIds)`

Checks if the current account can promote the specified participants.

canPromote(
  groupId: string | Wid,
  participantsIds: (string | Wid) | (string | Wid)[]
): Promise<boolean>

`WPP.group.canDemote(groupId, participantsIds)`

Checks if the current account can demote the specified participants.

canDemote(
  groupId: string | Wid,
  participantsIds: (string | Wid) | (string | Wid)[]
): Promise<boolean>

`WPP.group.canRemove(groupId, participantsIds)`

Checks if the current account can remove the specified participants.

canRemove(
  groupId: string | Wid,
  participantsIds: (string | Wid) | (string | Wid)[]
): Promise<boolean>

const groupId = '120363000000000001@g.us';
const targetId = '15550001234@c.us';

if (await WPP.group.canAdd(groupId)) {
  await WPP.group.addParticipants(groupId, targetId);
}

if (await WPP.group.canPromote(groupId, targetId)) {
  await WPP.group.promoteParticipants(groupId, targetId);
}

Self-role checks

These three functions check the current account’s own membership role. They take only a groupId and return a boolean.

`WPP.group.iAmMember(groupId)`

Returns true if the current account is a member of the group.

iAmMember(groupId: string | Wid): Promise<boolean>

`WPP.group.iAmAdmin(groupId)`

Returns true if the current account is an admin.

iAmAdmin(groupId: string | Wid): Promise<boolean>

`WPP.group.iAmSuperAdmin(groupId)`

Returns true if the current account is the group creator (super admin).

iAmSuperAdmin(groupId: string | Wid): Promise<boolean>

`WPP.group.iAmRestrictedMember(groupId)`

Returns true if the current account is a restricted member (cannot send messages in announcement groups).

iAmRestrictedMember(groupId: string | Wid): Promise<boolean>

const groupId = '120363000000000001@g.us';
console.log('Member:', await WPP.group.iAmMember(groupId));
console.log('Admin:', await WPP.group.iAmAdmin(groupId));
console.log('Super admin:', await WPP.group.iAmSuperAdmin(groupId));

Group info

`WPP.group.getAllGroups()`

Returns all groups the current account belongs to.

getAllGroups(): Promise<ChatModel[]>

const groups = await WPP.group.getAllGroups();
console.log('Total groups:', groups.length);

`WPP.group.getGroupSizeLimit()`

Returns the maximum number of participants allowed in a group on the current WhatsApp Web version.

getGroupSizeLimit(): Promise<number>

const limit = await WPP.group.getGroupSizeLimit();
console.log('Max group size:', limit);

Invite links

`WPP.group.getInviteCode(groupId)`

Returns the current invite code for a group (without the full URL prefix). Requires admin access.

getInviteCode(groupId: string | Wid): Promise<string>

groupId

string | Wid

required

The @g.us WID of the group.

const code = await WPP.group.getInviteCode('120363000000000001@g.us');
const link = 'https://chat.whatsapp.com/' + code;
console.log('Invite link:', link);

`WPP.group.revokeInviteCode(groupId)`

Revokes the current invite code and generates a new one. Old links will stop working immediately.

revokeInviteCode(groupId: string | Wid): Promise<string>

groupId

string | Wid

required

The @g.us WID of the group.

const newCode = await WPP.group.revokeInviteCode('120363000000000001@g.us');
const newLink = 'https://chat.whatsapp.com/' + newCode;

Revoking the invite code immediately invalidates all previously shared links. Anyone who has not joined yet will need the new link.

`WPP.group.getGroupInfoFromInviteCode(inviteCode)`

Fetches group metadata (name, description, participant list, owner) from an invite code — without actually joining the group.

getGroupInfoFromInviteCode(inviteCode: string): Promise<GroupInfo>

inviteCode

string

required

An invite code or a full invite URL.

const info = await WPP.group.getGroupInfoFromInviteCode('AbCdEf123456');
console.log('Group name:', info.subject);
console.log('Owner:', info.owner);
console.log('Participants:', info.participants.length);

Membership requests

When a group has “Approval required to join” enabled, new members must be approved by an admin before they can participate.

`WPP.group.getMembershipRequests(groupId)`

Returns all pending join requests for a group.

getMembershipRequests(groupId: string | Wid): Promise<{
  addedBy: Wid;
  id: Wid;
  parentGroupId?: Wid;
  requestMethod: 'InviteLink' | 'LinkedGroupJoin' | 'NonAdminAdd';
  t: number;
}[]>

groupId

string | Wid

required

The @g.us WID of the group.

`WPP.group.approve(groupId, membershipIds)`

Approves one or more pending membership requests.

approve(
  groupId: string | Wid,
  membershipIds: (string | Wid) | (string | Wid)[]
): Promise<{ error: any; wid: Wid }[]>

`WPP.group.reject(groupId, membershipIds)`

Rejects one or more pending membership requests.

reject(
  groupId: string | Wid,
  membershipIds: (string | Wid) | (string | Wid)[]
): Promise<{ error: any; wid: Wid }[]>

const groupId = '120363000000000001@g.us';

// List pending requests
const requests = await WPP.group.getMembershipRequests(groupId);
console.log(`${requests.length} pending request(s)`);

// Approve a specific requester
await WPP.group.approve(groupId, requests[0].id);

// Reject all remaining
const toReject = requests.slice(1).map(r => r.id);
await WPP.group.reject(groupId, toReject);

Group settings

`WPP.group.setSubject(groupId, subject)`

Changes the group name. Requires admin access.

setSubject(groupId: string | Wid, subject: string): Promise<true>

await WPP.group.setSubject('120363000000000001@g.us', 'New Group Name');

`WPP.group.setDescription(groupId, description)`

Sets the group description. Requires admin access.

setDescription(groupId: string | Wid, description: string): Promise<true>

await WPP.group.setDescription('120363000000000001@g.us', 'Welcome to our group!');

`WPP.group.setIcon(groupId, content)`

Sets the group profile picture. The image is automatically resized to 96×96 (thumbnail) and 640×640 (full). Returns upload metadata on success.

setIcon(groupId: string | Wid, content: string): Promise<{
  eurl: string;
  status: number;
  tag: string;
  token: string;
  _duplicate: boolean;
}>

groupId

string | Wid

required

The @g.us WID of the group.

content

string

required

A base64-encoded data URL of the image (e.g. data:image/jpeg;base64,....).

await WPP.group.setIcon('120363000000000001@g.us', 'data:image/jpeg;base64,....');

`WPP.group.removeIcon(groupId)`

Removes the group profile picture. Returns true on success.

removeIcon(groupId: string | Wid): Promise<boolean>

await WPP.group.removeIcon('120363000000000001@g.us');

`WPP.group.setProperty(groupId, property, value)`

Configures a group policy setting. Requires admin access.

setProperty(
  groupId: string | Wid,
  property: GroupProperty,
  value: 0 | 1 | 86400 | 604800 | 7776000 | boolean
): Promise<true>

groupId

string | Wid

required

The @g.us WID of the group.

property

GroupProperty

required

The setting to change. One of 'announcement', 'restrict', or 'ephemeral'.

value

boolean | number

required

The new value. For announcement and restrict, pass a boolean. For ephemeral, pass a duration in seconds.

Available GroupProperty values and their effects:

announcement — send-message permissions

Controls who can send messages in the group.

// Only admins can send messages
await WPP.group.setProperty('120363000000000001@g.us', 'announcement', true);

// All members can send messages
await WPP.group.setProperty('120363000000000001@g.us', 'announcement', false);

restrict — edit-info permissions

Controls who can change the group subject, description, and icon.

// Only admins can edit group info
await WPP.group.setProperty('120363000000000001@g.us', 'restrict', true);

// All members can edit group info
await WPP.group.setProperty('120363000000000001@g.us', 'restrict', false);

ephemeral — disappearing messages

Sets how long messages remain before auto-deletion. Pass 0 to disable.

// Disable disappearing messages
await WPP.group.setProperty('120363000000000001@g.us', 'ephemeral', 0);

// 24 hours
await WPP.group.setProperty('120363000000000001@g.us', 'ephemeral', 86400);

// 7 days
await WPP.group.setProperty('120363000000000001@g.us', 'ephemeral', 604800);

// 90 days
await WPP.group.setProperty('120363000000000001@g.us', 'ephemeral', 7776000);

Connection

Messaging

Contacts & Groups

Channels & Organization

Business

Account

Documentation Index

​Creating, joining, and leaving groups

​WPP.group.create(groupName, participantsIds, parentGroup?)

​WPP.group.join(inviteCode)

​WPP.group.leave(groupId)

​Managing participants

​WPP.group.addParticipants(groupId, participantsIds)

​WPP.group.removeParticipants(groupId, participantsIds)

​WPP.group.getParticipants(groupId)

​WPP.group.getPastParticipants(groupId)

​Admin roles

​WPP.group.promoteParticipants(groupId, participantsIds)

​WPP.group.demoteParticipants(groupId, participantsIds)

​Permission checks

​WPP.group.canAdd(groupId)

​WPP.group.canPromote(groupId, participantsIds)

​WPP.group.canDemote(groupId, participantsIds)

​WPP.group.canRemove(groupId, participantsIds)

​Self-role checks

​WPP.group.iAmMember(groupId)

​WPP.group.iAmAdmin(groupId)

​WPP.group.iAmSuperAdmin(groupId)

​WPP.group.iAmRestrictedMember(groupId)

​Group info

​WPP.group.getAllGroups()

​WPP.group.getGroupSizeLimit()

​Invite links

​WPP.group.getInviteCode(groupId)

​WPP.group.revokeInviteCode(groupId)

​WPP.group.getGroupInfoFromInviteCode(inviteCode)

​Membership requests

​WPP.group.getMembershipRequests(groupId)

​WPP.group.approve(groupId, membershipIds)

​WPP.group.reject(groupId, membershipIds)

​Group settings

​WPP.group.setSubject(groupId, subject)

​WPP.group.setDescription(groupId, description)

​WPP.group.setIcon(groupId, content)

​WPP.group.removeIcon(groupId)

​WPP.group.setProperty(groupId, property, value)

Build docs developers (and LLMs) love

Creating, joining, and leaving groups

`WPP.group.create(groupName, participantsIds, parentGroup?)`

`WPP.group.join(inviteCode)`

`WPP.group.leave(groupId)`

Managing participants

`WPP.group.addParticipants(groupId, participantsIds)`

`WPP.group.removeParticipants(groupId, participantsIds)`

`WPP.group.getParticipants(groupId)`

`WPP.group.getPastParticipants(groupId)`

Admin roles

`WPP.group.promoteParticipants(groupId, participantsIds)`

`WPP.group.demoteParticipants(groupId, participantsIds)`

Permission checks

`WPP.group.canAdd(groupId)`

`WPP.group.canPromote(groupId, participantsIds)`

`WPP.group.canDemote(groupId, participantsIds)`

`WPP.group.canRemove(groupId, participantsIds)`

Self-role checks

`WPP.group.iAmMember(groupId)`

`WPP.group.iAmAdmin(groupId)`

`WPP.group.iAmSuperAdmin(groupId)`

`WPP.group.iAmRestrictedMember(groupId)`

Group info

`WPP.group.getAllGroups()`

`WPP.group.getGroupSizeLimit()`

Invite links

`WPP.group.getInviteCode(groupId)`

`WPP.group.revokeInviteCode(groupId)`

`WPP.group.getGroupInfoFromInviteCode(inviteCode)`

Membership requests

`WPP.group.getMembershipRequests(groupId)`

`WPP.group.approve(groupId, membershipIds)`

`WPP.group.reject(groupId, membershipIds)`

Group settings

`WPP.group.setSubject(groupId, subject)`

`WPP.group.setDescription(groupId, description)`

`WPP.group.setIcon(groupId, content)`

`WPP.group.removeIcon(groupId)`

`WPP.group.setProperty(groupId, property, value)`