NexisChat Docs
Evolution API LiteFeatures

Managing Groups

Complete guide to WhatsApp group management through Evolution API Lite

Managing Groups

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

All group operations require authentication via API key and a valid connected instance. Group JIDs (identifiers) always end with @g.us.

Creating Groups

Create new WhatsApp groups with initial participants and settings.

Endpoint

POST /group/{instanceName}/create

Request Body

{
  "subject": "My New Group",
  "participants": ["5511999999999", "5511888888888"]
}
{
  "subject": "Project Team",
  "participants": ["5511999999999", "5511888888888", "5511777777777"],
  "description": "Team collaboration group for the new project",
  "promoteParticipants": true
}

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

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

{
  "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

Get All Groups

Retrieve all groups the instance is part of.

Endpoint

GET /group/{instanceName}/fetchAllGroups?getParticipants=true

Parameters

  • getParticipants: Set to "true" to include participant details, "false" for basic info only

cURL Example

curl -X GET "https://your-api-url/group/your-instance/fetchAllGroups?getParticipants=true" \
  -H "apikey: your-api-key"

Get Specific Group Info

Get detailed information about a specific group.

Endpoint

GET /group/{instanceName}/findGroupInfos?groupJid={groupJid}

cURL Example

curl -X GET "https://your-api-url/group/your-instance/findGroupInfos?groupJid=120363123456789012@g.us" \
  -H "apikey: your-api-key"

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

Get Group Participants

Retrieve the list of participants in a group.

Endpoint

GET /group/{instanceName}/participants?groupJid={groupJid}

cURL Example

curl -X GET "https://your-api-url/group/your-instance/participants?groupJid=120363123456789012@g.us" \
  -H "apikey: your-api-key"

Update Participants

Add, remove, promote, or demote group participants.

Endpoint

POST /group/{instanceName}/updateParticipant

Request Body

{
  "groupJid": "120363123456789012@g.us",
  "action": "add",
  "participants": ["5511777777777", "5511666666666"]
}
{
  "groupJid": "120363123456789012@g.us",
  "action": "remove",
  "participants": ["5511777777777"]
}
{
  "groupJid": "120363123456789012@g.us",
  "action": "promote",
  "participants": ["5511888888888"]
}
{
  "groupJid": "120363123456789012@g.us",
  "action": "demote",
  "participants": ["5511888888888"]
}

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

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

Update Group Subject (Name)

Change the group name/title.

Endpoint

POST /group/{instanceName}/updateGroupSubject

Request Body

{
  "groupJid": "120363123456789012@g.us",
  "subject": "New Group Name"
}

cURL Example

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

Change or remove the group description.

Endpoint

POST /group/{instanceName}/updateGroupDescription

Request Body

{
  "groupJid": "120363123456789012@g.us",
  "description": "Updated team collaboration group with new objectives"
}
{
  "groupJid": "120363123456789012@g.us",
  "description": ""
}

cURL Example

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

Change the group profile picture.

Endpoint

POST /group/{instanceName}/updateGroupPicture

Request Body

{
  "groupJid": "120363123456789012@g.us",
  "image": "https://example.com/new-group-picture.jpg"
}

You can provide the image as a URL or as base64 encoded data using the format: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...

cURL Example

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

Configure group permissions and settings.

Endpoint

POST /group/{instanceName}/updateSetting

Request Body

{
  "groupJid": "120363123456789012@g.us",
  "action": "restrict",
  "restrict": true
}
{
  "groupJid": "120363123456789012@g.us",
  "action": "announce",
  "announce": true
}

Settings

  • restrict: When true, only admins can send messages
  • announce: When true, only admins can send messages (announcement mode)

cURL Example

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

Create an invitation link for the group.

Endpoint

POST /group/{instanceName}/inviteCode

Request Body

{
  "groupJid": "120363123456789012@g.us"
}

cURL Example

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

{
  "inviteCode": "ABC123DEF456",
  "inviteUrl": "https://chat.whatsapp.com/ABC123DEF456"
}

Revoke the current invitation link and generate a new one.

Endpoint

POST /group/{instanceName}/revokeInviteCode

Request Body

{
  "groupJid": "120363123456789012@g.us"
}

cURL Example

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

Leave Group

Remove the instance from a group.

Endpoint

POST /group/{instanceName}/leaveGroup

Request Body

{
  "groupJid": "120363123456789012@g.us"
}

cURL Example

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"
  }'

If you are the group owner, leaving will transfer ownership to another admin. If no other admins exist, the group may be deleted.

Group Privacy Settings

Join by Invite Code

Join a group using an invitation code.

Endpoint

POST /group/{instanceName}/joinGroup

Request Body

{
  "inviteCode": "ABC123DEF456"
}

cURL Example

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

Common errors when managing groups:

Insufficient Permissions

{
  "error": true,
  "message": "Insufficient permissions to perform this action",
  "code": "INSUFFICIENT_PERMISSIONS"
}

Group Not Found

{
  "error": true,
  "message": "Group not found or instance is not a participant",
  "code": "GROUP_NOT_FOUND"
}

Invalid Participant

{
  "error": true,
  "message": "One or more participants are invalid or not on WhatsApp",
  "code": "INVALID_PARTICIPANTS"
}

Best Practices

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

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

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

Avoid rapid group operations to prevent being blocked by WhatsApp.

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

Next Steps

Sending Messages

Complete guide to sending all types of WhatsApp messages through Evolution API Lite

Chats and Contacts

Complete guide to managing chats, contacts, and profiles through Evolution API Lite