👥 Groups

Manage WhatsApp groups with the API.

Features#

Here’s the list of features that are available by 🏭 Engines:

API#

• {session} - use the session name for Whatsapp instance that you created with POST /api/session endpoint
• {groupId} - group id in format 123123123123@g.us. You can get the id in a few ways:
  • By handling incoming message webhook.
  • By getting all groups (see below).
  • By creating a new group and saving the id.

Create a new group#

POST /api/{session}/groups

{
  "name": "Group name",
  "participants": [
    {
      "id": "123123123123@c.us"
    }
  ]
}

Get all groups#

GET /api/{session}/groups

Response: depends on 🏭 Engine you use.

Query parameters:

GET /api/{session}/groups?limit=10&offset=0&sortBy=subject&sortOrder=desc

If you see timeout or the request takes too long - consider using limit parameter to get objects in smaller chunks

• limit=10 - limit the number of chats to return
• offset=0 - skip the number of chats from the start
• sortBy={field} - sort by field
  • sortBy=id - sort by group id
  • sortBy=subject - sort by group subject
• sortOrder=desc|asc - sort order
  • desc - descending order (New first, A-Z)
  • asc - ascending order (Old first, Z-A)
• exclude=participants - you can exclude participants data from the response

Get groups count#

Get the total number of groups

GET /api/{session}/groups/count

{
  "count": 10
}

Join group#

If you have invite URL for a group (like https://chat.whatsapp.com/invitecode), you can

POST /api/{session}/groups/join

{
  "code": "invitecode"
}

or using full link:

{
  "code": "https://chat.whatsapp.com/invitecode"
}

{
  "id": "123123123@g.us"
}

Get join info for group#

If you have invite URL for a group (like https://chat.whatsapp.com/invitecode), you can get group info:

GET /api/{session}/groups/join-info?code=invitecode

or using full link (remember to encode the URL)

GET /api/{session}/groups/join-info?code=https%3A%2F%2Fchat.whatsapp.com%2Finvitecode

Response depends on engine you’re using

Refresh groups#

If you see any inconsistency in groups list or in participants list, you can refresh the groups from the WhatsApp server:

POST /api/{session}/groups/refresh

⚠️ Do not call it frequently, it can lead to rate-overlimit error. Usually groups API has all up-to-date information.

Get the group#

GET /api/{session}/groups/{groupId}

Delete the group#

DELETE /api/{session}/groups/{groupId}

Leave the group#

POST /api/{session}/groups/{groupId}/leave

Group Picture#

You can get, set and remove group picture

Get Group Picture#

GET /api/{SESSION}/groups/{ID}/picture?refresh=false

• {SESSION} - session name
• {ID} - group id. Remember to encode @ symbol - 123123123123%40g.us
• refresh=True - force refresh the picture. By default, we cache it 24 hours. Do not frequently refresh the picture to avoid rate-overlimit error.

{
  "url": "https://example.com/picture.jpg"
}

• url can be null if there’s no picture for the group

Set Group Picture#

👉 Available in WAHA Plus version.

PUT /api/{SESSION}/groups/{ID}/picture

• {SESSION} - session name
• {ID} - group id. Remember to encode @ symbol - 123123123123%40g.us

{
  "file": {
    "url": "https://github.com/devlikeapro/waha/raw/core/examples/waha.jpg"
  }
}

{
  "file": {
    "data": "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"
  }
}

{
  "success": true
}

Delete Group Picture#

👉 Available in WAHA Plus version.

DELETE /api/{SESSION}/groups/{ID}/picture

• {SESSION} - session name
• {ID} - group id. Remember to encode @ symbol - 123123123123%40g.us

{
  "success": true
}

Set group subject#

Updates the group subject.

Returns true if the subject was properly updated. This can return false if the user does not have the necessary permissions.

PUT /api/{session}/groups/{groupId}/subject

{
  "subject": "Group name"
}

Set group description#

Updates the group description.

Returns true if the subject was properly updated. This can return false if the user does not have the necessary permissions.

PUT /api/{session}/groups/{groupId}/description

{
  "description": "Group description"
}

Security - update group info#

Updates the group settings to only allow admins to edit group info (title, description, photo).

PUT /api/{session}/groups/{groupId}/settings/security/info-admin-only

{
  "adminsOnly": true
}

Get the group settings to only allow admins to edit group info (title, description, photo).

GET /api/{session}/groups/{groupId}/settings/security/info-admin-only

{
  "adminsOnly": true
}

Returns true if the setting was properly updated. This can return false if the user does not have the necessary permissions.

Security - who can send messages#

Updates the group settings to only allow admins to send messages.

PUT /api/{session}/groups/{groupId}/settings/security/messages-admin-only

{
  "adminsOnly": true
}

Returns true if the setting was properly updated. This can return false if the user does not have the necessary permissions.

Get the group settings to only allow admins to send messages.

GET /api/{session}/groups/{groupId}/settings/security/messages-admin-only

{
  "adminsOnly": true
}

Participants#

Get participants v2#

Get list of participants with the “almost” the same response across engines

GET /api/{session}/groups/{groupId}/participants/v2

[
  {
    "id": "111111111111@c.us",
    "role": "participant"
  },
  {
    "id": "222222222222@c.us",
    "role": "superadmin"
  },
  {
    "id": "33333333333@c.us",
    "role": "participant"
  }
]

Role:

• left
• participant
• admin
• superadmin

Get participants#

GET /api/{session}/groups/{groupId}/participants

Add participants#

POST /api/{session}/groups/{groupId}/participants/add

{
  "participants": [
    {
      "id": "123123123123@c.us"
    }
  ]
}

Remove participants#

POST /api/{session}/groups/{groupId}/participants/remove

{
  "participants": [
    {
      "id": "123123123123@c.us"
    }
  ]
}

Admin#

Promote to admin#

Promote participants to admin users.

POST /api/{session}/groups/{groupId}/admin/promote

{
  "participants": [
    {
      "id": "123123123123@c.us"
    }
  ]
}

Demote to regular users#

Demote participants by to regular users.

POST /api/{session}/groups/{groupId}/admin/demote

{
  "participants": [
    {
      "id": "123123123123@c.us"
    }
  ]
}

Invite code#

Get invite code#

GET /api/{session}/groups/{groupId}/invite-code

Then you can put it in the url https://chat.whatsapp.com/{inviteCode} and send it to contacts.

Revoke invite code#

Invalidates the current group invite code and generates a new one.

POST /api/{session}/groups/{groupId}/invite-code/revoke

Events#

Read more about 🔄 Events.

group.v2.join#

group.v2.join happens when you join or are added to a group.

{
  "event": "group.v2.join",
  "session": "default",
  "payload": {
    "group": {
      "id": "1231231232@g.us",
      "subject": "Work Group",
      "description": "Group description",
      "invite": "https://chat.whatsapp.com/invitecode",
      "membersCanAddNewMember": true,
      "membersCanSendMessages": true,
      "newMembersApprovalRequired": true,
      "participants": [
        {
          "id": "99999@c.us",
          "role": "participant"
        }
      ]
    },
    "timestamp": 789456123,
    "_data": {}
  }
}

• group - group information
  • id - group ID
  • subject - group name
  • description - group description
  • invite - invite link
  • membersCanAddNewMember - if members can add new members
  • membersCanSendMessages - if members can send messages
  • newMembersApprovalRequired - if new members need approval from admins
  • participants - list of participants (check group.v2.participants for more details)
• timestamp - event timestamp
• _data - engine specific data

group.v2.leave#

group.v2.leave happens when you leave or are removed from a group.

{
  "event": "group.v2.leave",
  "session": "default",
  "payload": {
    "group": {
      "id": "1231231232@g.us"
    },
    "timestamp": 789456123,
    "_data": {}
  }
}

• group.id - group ID
• timestamp - event timestamp
• _data - engine specific data

group.v2.participants#

group.v2.participants happens when someone join or leave a group.

ℹ️ It might duplicate group.v2.join and group.v2.leave events for your ID.

{
  "event": "group.v2.participants",
  "session": "default",
  "payload": {
    "type": "join",
    "timestamp": 1666943582,
    "group": {
      "id": "123456789@g.us"
    },
    "participants": [
      {
        "id": "123456789@c.us",
        "role": "participant"
      }
    ],
    "_data": {}
  }
}

• type - event type. Possible values:
  • join - when someone joins the group
  • leave - when someone leaves the group
  • promote - when someone is promoted to admin
  • demote - when someone is demoted to regular participant
• participants - list of participants (contains only changed participants)
  • id - participant ID
  • role - participant role. Possible values:
    • left - left the group
    • participant - regular participant
    • admin - group admin
    • superadmin - group super admin
• _data - engine specific data

group.v2.update#

group.v2.update happens when the group information is updated.

{
  "event": "group.v2.update",
  "session": "default",
  "payload": {
    "group": {
      "id": "1231231232@g.us",
      "subject": "New Work Group Name"
    },
    "timestamp": 789456123,
    "_data": {}
  }
}

• group - group information with updates field (may contain all fields in some engines)
  • See details in group.v2.join
• timestamp - event timestamp
• _data - engine specific data

group.join#

⚠️ DEPRECATED. payload has engine specific data. Use group.v2.leave instead.

{
  "event": "group.join",
  "session": "default",
  "engine": "WEBJS",
  "payload": {
    ...
  }
}

group.leave#

⚠️ DEPRECATED. payload has engine specific data. Use group.v2.leave instead.

{
  "event": "group.leave",
  "session": "default",
  "engine": "WEBJS",
  "payload": {
    ...
  }
}