Skip to content
NexisChat Docs

Managing Groups

Managing Groups

Section titled “Managing Groups”

Evolution API Lite provides comprehensive group management capabilities, allowing you to create groups, manage participants, update settings, and handle invitations programmatically.

Creating Groups

Section titled “Creating Groups”

Create new WhatsApp groups with initial participants and settings.

Endpoint

Section titled “Endpoint”
POST /group/{instanceName}/create

Request Body

Section titled “Request Body”
{
  "subject": "My New Group",
  "participants": ["5511999999999", "5511888888888"]
}

Parameters

Section titled “Parameters”
  • subject (required): The group name/title
  • participants (required): Array of phone numbers to add as initial participants
  • description (optional): Group description text
  • promoteParticipants (optional): Whether to promote added participants to admin

cURL Example

Section titled “cURL Example”
Terminal window
curl -X POST "https://your-api-url/group/your-instance/create" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "subject": "Development Team",
    "participants": ["5511999999999", "5511888888888"],
    "description": "Daily standup and project updates"
  }'

Response

Section titled “Response”
{
  "id": "120363123456789012@g.us",
  "subject": "Development Team",
  "creation": 1640995200,
  "owner": "5511999999999@s.whatsapp.net",
  "participants": [
    {
      "id": "5511999999999@s.whatsapp.net",
      "admin": "admin"
    },
    {
      "id": "5511888888888@s.whatsapp.net",
      "admin": null
    }
  ]
}

Fetching Group Information

Section titled “Fetching Group Information”

Get All Groups

Section titled “Get All Groups”

Retrieve all groups the instance is part of.

Endpoint

Section titled “Endpoint”
GET /group/{instanceName}/fetchAllGroups?getParticipants=true

Parameters

Section titled “Parameters”
  • getParticipants: Set to “true” to include participant details, “false” for basic info only

cURL Example

Section titled “cURL Example”
Terminal window
curl -X GET "https://your-api-url/group/your-instance/fetchAllGroups?getParticipants=true" \
  -H "apikey: your-api-key"

Get Specific Group Info

Section titled “Get Specific Group Info”

Get detailed information about a specific group.

Endpoint

Section titled “Endpoint”
GET /group/{instanceName}/findGroupInfos?groupJid={groupJid}

cURL Example

Section titled “cURL Example”
Terminal window
curl -X GET "https://your-api-url/group/your-instance/findGroupInfos?groupJid=120363123456789012@g.us" \
  -H "apikey: your-api-key"

Response

Section titled “Response”
{
  "id": "120363123456789012@g.us",
  "subject": "Development Team",
  "creation": 1640995200,
  "owner": "5511999999999@s.whatsapp.net",
  "desc": "Daily standup and project updates",
  "descOwner": "5511999999999@s.whatsapp.net",
  "descId": "12345",
  "restrict": false,
  "announce": false,
  "size": 5,
  "participants": [
    {
      "id": "5511999999999@s.whatsapp.net",
      "admin": "admin"
    }
  ]
}

Managing Participants

Section titled “Managing Participants”

Get Group Participants

Section titled “Get Group Participants”

Retrieve the list of participants in a group.

Endpoint

Section titled “Endpoint”
GET /group/{instanceName}/participants?groupJid={groupJid}

cURL Example

Section titled “cURL Example”
Terminal window
curl -X GET "https://your-api-url/group/your-instance/participants?groupJid=120363123456789012@g.us" \
  -H "apikey: your-api-key"

Update Participants

Section titled “Update Participants”

Add, remove, promote, or demote group participants.

Endpoint

Section titled “Endpoint”
POST /group/{instanceName}/updateParticipant

Request Body

Section titled “Request Body”
{
  "groupJid": "120363123456789012@g.us",
  "action": "add",
  "participants": ["5511777777777", "5511666666666"]
}

Actions

Section titled “Actions”
  • add: Add new participants to the group
  • remove: Remove participants from the group
  • promote: Promote participants to admin status
  • demote: Remove admin status from participants

cURL Example

Section titled “cURL Example”
Terminal window
curl -X POST "https://your-api-url/group/your-instance/updateParticipant" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "groupJid": "120363123456789012@g.us",
    "action": "add",
    "participants": ["5511777777777"]
  }'

Updating Group Settings

Section titled “Updating Group Settings”

Update Group Subject (Name)

Section titled “Update Group Subject (Name)”

Change the group name/title.

Endpoint

Section titled “Endpoint”
POST /group/{instanceName}/updateGroupSubject

Request Body

Section titled “Request Body”
{
  "groupJid": "120363123456789012@g.us",
  "subject": "New Group Name"
}

cURL Example

Section titled “cURL Example”
Terminal window
curl -X POST "https://your-api-url/group/your-instance/updateGroupSubject" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "groupJid": "120363123456789012@g.us",
    "subject": "Updated Development Team"
  }'

Update Group Description

Section titled “Update Group Description”

Change or remove the group description.

Endpoint

Section titled “Endpoint”
POST /group/{instanceName}/updateGroupDescription

Request Body

Section titled “Request Body”
{
  "groupJid": "120363123456789012@g.us",
  "description": "Updated team collaboration group with new objectives"
}

cURL Example

Section titled “cURL Example”
Terminal window
curl -X POST "https://your-api-url/group/your-instance/updateGroupDescription" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "groupJid": "120363123456789012@g.us",
    "description": "New project guidelines and daily updates"
  }'

Update Group Picture

Section titled “Update Group Picture”

Change the group profile picture.

Endpoint

Section titled “Endpoint”
POST /group/{instanceName}/updateGroupPicture

Request Body

Section titled “Request Body”
{
  "groupJid": "120363123456789012@g.us",
  "image": "https://example.com/new-group-picture.jpg"
}

cURL Example

Section titled “cURL Example”
Terminal window
curl -X POST "https://your-api-url/group/your-instance/updateGroupPicture" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "groupJid": "120363123456789012@g.us",
    "image": "https://example.com/group-logo.png"
  }'

Update Group Settings

Section titled “Update Group Settings”

Configure group permissions and settings.

Endpoint

Section titled “Endpoint”
POST /group/{instanceName}/updateSetting

Request Body

Section titled “Request Body”
{
  "groupJid": "120363123456789012@g.us",
  "action": "restrict",
  "restrict": true
}

Settings

Section titled “Settings”
  • restrict: When true, only admins can send messages
  • announce: When true, only admins can send messages (announcement mode)

cURL Example

Section titled “cURL Example”
Terminal window
curl -X POST "https://your-api-url/group/your-instance/updateSetting" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "groupJid": "120363123456789012@g.us",
    "action": "restrict",
    "restrict": true
  }'

Group Invitations

Section titled “Group Invitations”
Section titled “Generate Invite Link”

Create an invitation link for the group.

Endpoint

Section titled “Endpoint”
POST /group/{instanceName}/inviteCode

Request Body

Section titled “Request Body”
{
  "groupJid": "120363123456789012@g.us"
}

cURL Example

Section titled “cURL Example”
Terminal window
curl -X POST "https://your-api-url/group/your-instance/inviteCode" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "groupJid": "120363123456789012@g.us"
  }'

Response

Section titled “Response”
{
  "inviteCode": "ABC123DEF456",
  "inviteUrl": "https://chat.whatsapp.com/ABC123DEF456"
}
Section titled “Revoke Invite Link”

Revoke the current invitation link and generate a new one.

Endpoint

Section titled “Endpoint”
POST /group/{instanceName}/revokeInviteCode

Request Body

Section titled “Request Body”
{
  "groupJid": "120363123456789012@g.us"
}

cURL Example

Section titled “cURL Example”
Terminal window
curl -X POST "https://your-api-url/group/your-instance/revokeInviteCode" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "groupJid": "120363123456789012@g.us"
  }'

Leaving Groups

Section titled “Leaving Groups”

Leave Group

Section titled “Leave Group”

Remove the instance from a group.

Endpoint

Section titled “Endpoint”
POST /group/{instanceName}/leaveGroup

Request Body

Section titled “Request Body”
{
  "groupJid": "120363123456789012@g.us"
}

cURL Example

Section titled “cURL Example”
Terminal window
curl -X POST "https://your-api-url/group/your-instance/leaveGroup" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "groupJid": "120363123456789012@g.us"
  }'

Group Privacy Settings

Section titled “Group Privacy Settings”

Join by Invite Code

Section titled “Join by Invite Code”

Join a group using an invitation code.

Endpoint

Section titled “Endpoint”
POST /group/{instanceName}/joinGroup

Request Body

Section titled “Request Body”
{
  "inviteCode": "ABC123DEF456"
}

cURL Example

Section titled “cURL Example”
Terminal window
curl -X POST "https://your-api-url/group/your-instance/joinGroup" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "inviteCode": "ABC123DEF456"
  }'

Error Handling

Section titled “Error Handling”

Common errors when managing groups:

Insufficient Permissions

Section titled “Insufficient Permissions”
{
  "error": true,
  "message": "Insufficient permissions to perform this action",
  "code": "INSUFFICIENT_PERMISSIONS"
}

Group Not Found

Section titled “Group Not Found”
{
  "error": true,
  "message": "Group not found or instance is not a participant",
  "code": "GROUP_NOT_FOUND"
}

Invalid Participant

Section titled “Invalid Participant”
{
  "error": true,
  "message": "One or more participants are invalid or not on WhatsApp",
  "code": "INVALID_PARTICIPANTS"
}

Best Practices

Section titled “Best Practices”

  1. Verify Group Membership

    Always check if the instance is a member of the group before performing operations.

  2. Handle Permissions

    Ensure the instance has admin privileges for actions that require them (adding/removing participants, changing settings).

  3. Validate Phone Numbers

    Use the WhatsApp number validation endpoint before adding participants to groups.

  4. Implement Rate Limiting

    Avoid rapid group operations to prevent being blocked by WhatsApp.

  5. Monitor Group Changes

    Set up webhooks to receive notifications about group membership changes and updates.

Next Steps

Section titled “Next Steps”