Groups

Baileys exposes a full set of group management methods on the sock object. Most operations that modify a group — changing its name, description, settings, or participants — require your account to be an admin of that group.

You must be a group admin to perform most of the operations on this page. Attempting them as a regular member will throw an error.

Create a group

Pass a subject (the group name) and an array of participant JIDs. The resolved value contains a gid field with the new group’s JID.

// title & participants
const group = await sock.groupCreate('My Fab Group', ['[email protected]', '[email protected]'])
console.log('created group with id: ' + group.gid)
await sock.sendMessage(group.id, { text: 'hello there' }) // say hello to everyone on the group

Add, remove, promote, or demote participants

groupParticipantsUpdate handles all four participant actions in a single method. Pass the group JID, an array of participant JIDs, and one of the four action strings.

// id & people to add to the group (will throw error if it fails)
await sock.groupParticipantsUpdate(
    jid,
    ['[email protected]', '[email protected]'],
    'add' // replace this parameter with 'remove' or 'demote' or 'promote'
)

The action parameter accepts 'add' | 'remove' | 'demote' | 'promote'.

Update the group subject and description

await sock.groupUpdateSubject(jid, 'New Subject!')

await sock.groupUpdateDescription(jid, 'New Description!')

Change group settings

groupSettingUpdate controls two independent aspects: who can send messages, and who can change group settings.

// only allow admins to send messages
await sock.groupSettingUpdate(jid, 'announcement')
// allow everyone to send messages
await sock.groupSettingUpdate(jid, 'not_announcement')
// allow everyone to modify the group's settings -- like display picture etc.
await sock.groupSettingUpdate(jid, 'unlocked')
// only allow admins to modify the group's settings
await sock.groupSettingUpdate(jid, 'locked')

Setting value	Effect
`announcement`	Only admins can send messages
`not_announcement`	All members can send messages
`locked`	Only admins can change group settings
`unlocked`	All members can change group settings

Leave a group

// will throw error if it fails
await sock.groupLeave(jid)

Invite links

Get the invite code

The raw code value is just the token. Prepend 'https://chat.whatsapp.com/' to build a shareable link.

const code = await sock.groupInviteCode(jid)
console.log('group code: ' + code)
// shareable link:
const link = 'https://chat.whatsapp.com/' + code

Revoke the invite code

Revoking generates a new code and invalidates all previously shared links.

const code = await sock.groupRevokeInvite(jid)
console.log('New group code: ' + code)

Join using an invite code

Pass only the raw code, not the full URL.

const response = await sock.groupAcceptInvite(code)
console.log('joined to: ' + response)

The code must not include the https://chat.whatsapp.com/ prefix — pass only the token portion.

Get group info from an invite code

You can inspect a group before joining it.

const response = await sock.groupGetInviteInfo(code)
console.log('group information: ' + response)

Join using a `groupInviteMessage`

When you receive an in-chat group invite message, you can accept it directly.

const response = await sock.groupAcceptInviteV4(jid, groupInviteMessage)
console.log('joined to: ' + response)

Query group metadata

Fetch the current participants, name, description, and other properties for any group you belong to.

const metadata = await sock.groupMetadata(jid)
console.log(metadata.id + ', title: ' + metadata.subject + ', description: ' + metadata.desc)

The GroupMetadata object includes:

Field	Type	Description
`id`	`string`	Group JID
`subject`	`string`	Group name
`desc`	`string \| undefined`	Group description
`owner`	`string \| undefined`	JID of the group creator
`participants`	`GroupParticipant[]`	Full participant list with admin flags
`ephemeralDuration`	`number \| undefined`	Active disappearing message timer (seconds)
`announce`	`boolean \| undefined`	`true` when only admins can send
`restrict`	`boolean \| undefined`	`true` when only admins can change settings
`memberAddMode`	`boolean \| undefined`	`true` when all members can add participants
`joinApprovalMode`	`boolean \| undefined`	`true` when join requests need approval

Get all participating groups

Returns a map of group JIDs to their GroupMetadata. Also emits a groups.update event internally.

const response = await sock.groupFetchAllParticipating()
console.log(response)

Join request management

When joinApprovalMode is enabled on a group, new members must be approved before they can participate.

List pending join requests

const response = await sock.groupRequestParticipantsList(jid)
console.log(response)

Approve or reject requests

const response = await sock.groupRequestParticipantsUpdate(
    jid, // group id
    ['[email protected]', '[email protected]'],
    'approve' // or 'reject'
)
console.log(response)

Toggle ephemeral (disappearing) messages

Pass 0 to disable disappearing messages, or one of the durations below to enable them.

await sock.groupToggleEphemeral(jid, 86400)

Duration	Seconds
Off	`0`
24 hours	`86400`
7 days	`604800`
90 days	`7776000`

Change who can add members

Control whether all members or only admins can add new participants to the group.

await sock.groupMemberAddMode(
    jid,
    'all_member_add' // or 'admin_add'
)

Mode	Effect
`all_member_add`	Any member can add participants
`admin_add`	Only admins can add participants

Caching group metadata

If you use groups heavily, Baileys recommends setting up a cachedGroupMetadata function on your socket config to avoid redundant network requests.

import NodeCache from '@cacheable/node-cache'

const groupCache = new NodeCache({ stdTTL: 5 * 60, useClones: false })

const sock = makeWASocket({
    cachedGroupMetadata: async (jid) => groupCache.get(jid)
})

sock.ev.on('groups.update', async ([event]) => {
    const metadata = await sock.groupMetadata(event.id)
    groupCache.set(event.id, metadata)
})

sock.ev.on('group-participants.update', async (event) => {
    const metadata = await sock.groupMetadata(event.id)
    groupCache.set(event.id, metadata)
})

Caching group metadata significantly reduces latency and the number of IQ queries sent to WhatsApp’s servers, especially in bots that handle many groups simultaneously.

Get Started

Authentication

Core Concepts

Messaging

Features

Advanced

Migration

Community

Create a group

Add, remove, promote, or demote participants

Update the group subject and description

Change group settings

Leave a group

Invite links

Get the invite code

Revoke the invite code

Join using an invite code

Get group info from an invite code

Join using a `groupInviteMessage`

Query group metadata

Get all participating groups

Join request management

List pending join requests

Approve or reject requests

Toggle ephemeral (disappearing) messages

Change who can add members

Caching group metadata

​Create a group

​Add, remove, promote, or demote participants

​Update the group subject and description

​Change group settings

​Leave a group

​Invite links

​Get the invite code

​Revoke the invite code

​Join using an invite code

​Get group info from an invite code

​Join using a groupInviteMessage

​Query group metadata

​Get all participating groups

​Join request management

​List pending join requests

​Approve or reject requests

​Toggle ephemeral (disappearing) messages

​Change who can add members

​Caching group metadata

Create a group

Add, remove, promote, or demote participants

Update the group subject and description

Change group settings

Leave a group

Invite links

Get the invite code

Revoke the invite code

Join using an invite code

Get group info from an invite code

Join using a `groupInviteMessage`

Query group metadata

Get all participating groups

Join request management

List pending join requests

Approve or reject requests

Toggle ephemeral (disappearing) messages

Change who can add members

Caching group metadata