Groups

Group IDs are assigned by WhatsApp. Keep the complete ID returned by a method or message event; do not derive it from a group name or participant numbers. See the Chat ID guide for accepted identifier forms and invite-token handling.

Create a groupCopy Anchor Link

createGroup requires a Restricted license. It returns a group object with a gid, or null if creation did not return a group. The connected account must also be able to create the group and add the listed contacts.

const created = await client.createGroup('Support updates', [
  '447700900000@c.us',
]);

if (!created?.gid) {
  throw new Error('The group was not created');
}

const groupId = created.gid;

See the exact createGroup contract and license guidance before using this method.

Participants and permissionsCopy Anchor Link

The embedded Client supports adding, removing, promoting, and demoting one participant at a time. These operations require group-administrator permissions, and each call returns true only when the runtime reports success.

const changed = await client.addParticipant(groupId, '447700900000@c.us');
if (!changed) {
  console.error('The participant was not added');
}

Use the participant method reference for the other operations and their exact signatures. Keep the returned contact IDs intact; see group filtering for matching incoming messages to a group allowlist.

Invite linksCopy Anchor Link

getGroupInviteLink and revokeGroupInviteLink operate on a group ID. The returned invite URL is a token for joining, not the group ID. Joining through a link requires a Restricted license. The embedded Client returns a group ID or false; the Easy API also accepts an option to return a chat object.

const inviteUrl = await client.getGroupInviteLink(groupId);
const result = await client.joinGroupViaLink(inviteUrl);

if (typeof result === 'string') {
  console.log('Joined group:', result);
} else {
  console.error('The invite did not return a group ID:', result);
}

The joinGroupViaLink contract includes its license tier and Easy API option. Check the result for your selected surface before treating the join as complete. Revoking an invite invalidates the old URL; retrieve and share the replacement only when your workflow needs one.

Other group operationsCopy Anchor Link

The generated Easy API catalog includes group reads and settings updates such as getGroupMembers, getGroupAdmins, and setGroupDescription. Method availability differs by client surface: the current embedded Client does not declare every Easy API group method, and its getGroupInfo, setGroupTitle, and setGroupDescription entries are unsupported. Check the exact method reference for your deployed surface before calling one:

• Group methods
• Licensed features

Membership eventsCopy Anchor Link

The runtime event map exposes group.participants.changed.global. Its change payload contains the group ID, action, affected participant IDs, and the actor when available:

import { ev } from '@open-wa/wa-automate';

ev.on('group.participants.changed.global', ({ change }) => {
  console.log(change.groupId, change.action, change.participantIds, change.by);
});

The event is a change notification, not a complete membership snapshot. Keep an application-owned group record if later actions depend on current state. See the event reference for its full type.