Skip to main content
Group admins can manage participants by adding or removing members and changing their admin status.

​
Adding and removing participants

The groupParticipantsUpdate function handles all participant management operations: 
// 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'
)
​
jid
string
required
The group JID
​
participants
string[]
required
Array of participant JIDs to update (must use @s.whatsapp.net format)
​
action
ParticipantAction
required
The action to perform: 'add', 'remove', 'promote', or 'demote'

​
Participant actions

​
Adding members

Add new participants to the group: 
const result = await sock.groupParticipantsUpdate(
    jid,
    ['[email protected]', '[email protected]'],
    'add'
)
The function returns an array of results for each participant: 
[
  { status: '200', jid: '[email protected]', content: BinaryNode },
  { status: '403', jid: '[email protected]', content: BinaryNode }
]
Status codes:
  • '200' - Successfully added
  • '403' - Forbidden (user privacy settings may prevent adding)
  • '408' - Request timeout
  • Other error codes indicate various failure reasons
Users with strict privacy settings may not be added to groups by non-contacts. In such cases, you’ll receive a '403' status code and the user won’t be added.

​
Removing members

Remove participants from the group: 
const result = await sock.groupParticipantsUpdate(
    jid,
    ['[email protected]'],
    'remove'
)
You cannot remove the group owner/creator. Attempting to do so will fail with an error.

​
Promoting to admin

Grant admin privileges to regular members: 
const result = await sock.groupParticipantsUpdate(
    jid,
    ['[email protected]', '[email protected]'],
    'promote'
)
After promotion, the users will have admin capabilities:
  • Add/remove participants (if group settings allow)
  • Promote/demote other members
  • Change group subject and description
  • Modify group settings
  • Manage invite codes
Only existing group admins can promote members to admin status.

​
Demoting admins

Remove admin privileges from group admins: 
const result = await sock.groupParticipantsUpdate(
    jid,
    ['[email protected]'],
    'demote'
)
Demoted users become regular members and lose all admin privileges.
You cannot demote the group owner/creator (superadmin). Attempting to demote the owner will fail.

​
Handling results

All participant update operations return an array of results showing the outcome for each participant: 
const results = await sock.groupParticipantsUpdate(
    jid,
    ['[email protected]', '[email protected]', '[email protected]'],
    'add'
)

results.forEach(result => {
    if (result.status === '200') {
        console.log(`Successfully added ${result.jid}`)
    } else {
        console.log(`Failed to add ${result.jid}: ${result.status}`)
    }
})
  • 200 - Success
  • 403 - Forbidden (privacy settings, not enough permissions, etc.)
  • 404 - User not found
  • 408 - Request timeout
  • 409 - Conflict (e.g., user already in group for ‘add’ action)
  • 500 - Internal server error

​
Batch operations

You can update multiple participants in a single call for better performance: 
// Add multiple users at once
await sock.groupParticipantsUpdate(
    jid,
    [
        '[email protected]',
        '[email protected]',
        '[email protected]',
        '[email protected]'
    ],
    'add'
)

// Promote multiple users to admin
await sock.groupParticipantsUpdate(
    jid,
    [
        '[email protected]',
        '[email protected]'
    ],
    'promote'
)
Batch operations are processed as a single request to WhatsApp’s servers, making them more efficient than individual calls.

​
Permission requirements

Different actions have different permission requirements:
ActionRequired RoleNotes
Add participantsAdmin*Depends on group’s member add mode setting
Remove participantsAdminCannot remove the owner
Promote to adminAdminOnly admins can promote
Demote adminAdminCannot demote the owner
*If the group’s memberAddMode is set to 'all_member_add', regular members can also add participants. See group settings for more details.

​
Best practices

1

Check permissions first

Before attempting participant updates, verify that your bot/user has admin privileges by checking the group metadata.
2

Handle errors gracefully

Always check the status codes in the response to handle failures appropriately.
3

Respect privacy settings

Be prepared for some users to have privacy settings that prevent them from being added to groups.
4

Use batch operations

When updating multiple participants, use a single call with an array rather than multiple individual calls.

​
Example: Complete participant management

// Check if we're an admin
const metadata = await sock.groupMetadata(groupJid)
const me = metadata.participants.find(p => p.id === sock.user.id)

if (!me?.admin) {
    console.log('Not an admin, cannot manage participants')
    return
}

// Add new members
const addResults = await sock.groupParticipantsUpdate(
    groupJid,
    ['[email protected]', '[email protected]'],
    'add'
)

// Check which users were successfully added
const successfullyAdded = addResults
    .filter(r => r.status === '200')
    .map(r => r.jid)

if (successfullyAdded.length > 0) {
    console.log('Successfully added:', successfullyAdded)
    
    // Promote one of them to admin
    await sock.groupParticipantsUpdate(
        groupJid,
        [successfullyAdded[0]],
        'promote'
    )
}

// Handle failed additions
const failed = addResults.filter(r => r.status !== '200')
if (failed.length > 0) {
    console.log('Failed to add:', failed)
}

Build docs developers (and LLMs) love

Get started for freeTalk to us