Manage Group Participants

Add, remove, promote, or demote participants in a WhatsApp group.

POST /group/updateParticipant/:instanceName

cURL (Add Participants)

curl --request POST \
  --url https://api.example.com/group/updateParticipant/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "groupJid": "[e-mail]",
    "action": "add",
    "participants": [
      "5511999999999",
      "5511888888888"
    ]
  }'

curl --request POST \
  --url https://api.example.com/group/updateParticipant/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "groupJid": "[e-mail]",
    "action": "promote",
    "participants": ["5511999999999"]
  }'

// Add participants
const response = await fetch(
  'https://api.example.com/group/updateParticipant/my-instance',
  {
    method: 'POST',
    headers: {
      'apikey': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      groupJid: '[e-mail]',
      action: 'add',
      participants: ['5511999999999', '5511888888888']
    })
  }
);

const data = await response.json();

import requests

# Remove participants
response = requests.post(
    'https://api.example.com/group/updateParticipant/my-instance',
    headers={
        'apikey': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'groupJid': '[e-mail]',
        'action': 'remove',
        'participants': ['5511999999999']
    }
)

data = response.json()

201 Success (Add)

{
  "success": true,
  "action": "add",
  "participants": [
    "[e-mail]",
    "[e-mail]"
  ],
  "results": [
    {
      "jid": "[e-mail]",
      "status": "success",
      "message": "Participant added successfully"
    },
    {
      "jid": "[e-mail]",
      "status": "success",
      "message": "Participant added successfully"
    }
  ]
}

{
  "success": true,
  "action": "promote",
  "participants": ["[e-mail]"],
  "results": [
    {
      "jid": "[e-mail]",
      "status": "success",
      "message": "Participant promoted to admin"
    }
  ]
}

{
  "error": "Invalid action",
  "message": "Action must be one of: add, remove, promote, demote"
}

{
  "error": "Insufficient permissions",
  "message": "You must be a group admin to perform this action"
}

{
  "error": "Group not found",
  "message": "The specified group does not exist"
}

Overview

You can manage group participants by adding new members, removing existing ones, or changing their admin status. You must be a group admin to perform these actions.

Only group admins can add, remove, promote, or demote participants. Attempting these actions as a regular member will fail.

Authentication

This endpoint requires authentication via the apikey header.

header.apikey · string · required

Your Evolution API key for authentication.

Path Parameters

path.instanceName · string · required

The name of your WhatsApp instance.

Request Body

groupJid · string · required

The WhatsApp group JID (can be provided with or without the @g.us suffix).

action · string · required

The action to perform on participants. Must be one of:

• add: Add new participants to the group
• remove: Remove participants from the group
• promote: Promote participants to admin status
• demote: Demote admins to regular member status

participants · string[] · required

Array of participant phone numbers in international format (e.g., [“5511999999999”, “5511888888888”]).

Response

success · boolean

Whether the operation completed successfully.

action · string

The action that was performed.

participants · array

Array of affected participant JIDs.

results · array

Detailed results for each participant.

Show properties

jid · string

Participant’s WhatsApp JID.

status · string

Result status (e.g., “success”, “error”, “already_member”).

message · string

Descriptive message about the result.

cURL (Add Participants)

curl --request POST \
  --url https://api.example.com/group/updateParticipant/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "groupJid": "[e-mail]",
    "action": "add",
    "participants": [
      "5511999999999",
      "5511888888888"
    ]
  }'

curl --request POST \
  --url https://api.example.com/group/updateParticipant/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "groupJid": "[e-mail]",
    "action": "promote",
    "participants": ["5511999999999"]
  }'

// Add participants
const response = await fetch(
  'https://api.example.com/group/updateParticipant/my-instance',
  {
    method: 'POST',
    headers: {
      'apikey': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      groupJid: '[e-mail]',
      action: 'add',
      participants: ['5511999999999', '5511888888888']
    })
  }
);

const data = await response.json();

import requests

# Remove participants
response = requests.post(
    'https://api.example.com/group/updateParticipant/my-instance',
    headers={
        'apikey': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'groupJid': '[e-mail]',
        'action': 'remove',
        'participants': ['5511999999999']
    }
)

data = response.json()

201 Success (Add)

{
  "success": true,
  "action": "add",
  "participants": [
    "[e-mail]",
    "[e-mail]"
  ],
  "results": [
    {
      "jid": "[e-mail]",
      "status": "success",
      "message": "Participant added successfully"
    },
    {
      "jid": "[e-mail]",
      "status": "success",
      "message": "Participant added successfully"
    }
  ]
}

{
  "success": true,
  "action": "promote",
  "participants": ["[e-mail]"],
  "results": [
    {
      "jid": "[e-mail]",
      "status": "success",
      "message": "Participant promoted to admin"
    }
  ]
}

{
  "error": "Invalid action",
  "message": "Action must be one of: add, remove, promote, demote"
}

{
  "error": "Insufficient permissions",
  "message": "You must be a group admin to perform this action"
}

{
  "error": "Group not found",
  "message": "The specified group does not exist"
}

Usage Notes

When adding participants, they will receive a group invitation notification. If their privacy settings prevent group adds, they’ll need to join manually using an invite link.

You can add multiple participants in a single request. The response will include individual status for each participant.

Super admins (group creators) cannot be demoted or removed through this endpoint.

Additional Endpoints

Get Participants List

To retrieve the list of group participants:

GET /group/participants/:instanceName?groupJid=[e-mail]

This returns an array of participant objects with their admin status.