Overview

Auth: TokenAccount or TokenInstance on every route. Each call validates the instance ownership. This section covers all /api/group/* routes: creation, listing, details, participant management, metadata updates, invite link reset, joining, and leaving. For communities (parent groups), see Communities.

Endpoints

Method	Path	Function
POST	`/api/group/create/:instance`	Create group
GET	`/api/group/list/:instance`	List groups
GET	`/api/group/info/:instance`	Group details
PUT	`/api/group/update/:instance`	Update name / description / picture / permissions
POST	`/api/group/participants/:instance`	Add / remove / promote / demote / approve / reject
POST	`/api/group/join/:instance`	Join via code / link
POST	`/api/group/resetLink/:instance`	Revoke and regenerate invite link
GET	`/api/group/requests/:instance`	List pending requests
DELETE	`/api/group/leave/:instance`	Leave group

Accepted identifiers

Most endpoints accept an identifier field, which can be:

Form	Example
Group JID	`120363406289005073@g.us`
Invite code	`ABC123XYZ`
Full link	`https://chat.whatsapp.com/ABC123XYZ`

Exceptions:

POST /api/group/join accepts only a code or link (no JID).
GET /api/community/listSubGroups requires a JID in the query ?communityJid=.

Data structures

`GroupInfo`

Standard response for the create and update routes.

{
  "name": "Dev Team",
  "jid": "120363406289005073@g.us",
  "description": "Technical discussions",
  "inviteCode": "ABC123XYZ",
  "inviteLink": "https://chat.whatsapp.com/ABC123XYZ",
  "createdBy": "5511999999999@s.whatsapp.net",
  "participantCount": 3,
  "participants": [
    { "jid": "5511999999999@s.whatsapp.net", "isAdmin": true, "isSuperAdmin": false }
  ],
  "groupSettings": {
    "membersCanEditInfo": true,
    "membersCanSendMessages": true,
    "membersCanAddOthers": false,
    "requireAdminApproval": false
  },
  "isCommunity": false,
  "isParent": false,
  "linkedParentJid": null
}

`GroupDetail`

Response from GET /info. Includes extra fields beyond GroupInfo: image, createdAt, metadata (author of the last name / description change), isEphemeral, isIncognito, isSuspended, isDefaultSubGroup.

`GroupPermissions`

Field	Type	WhatsApp meaning
`membersCanEditInfo`	bool	Inverse of `IsLocked`
`membersCanSendMessages`	bool	Inverse of `IsAnnounce`
`membersCanAddOthers`	bool	`MemberAddMode == AllMember`
`requireAdminApproval`	bool	`IsJoinApprovalRequired`

Error envelope

All routes use the API’s standard envelope:

{
  "success": false,
  "error": { "message": "Identifier is required" }
}

Error reference (summary)

Category	Message
Auth	`Not authorized to view group requests (must be admin)`
Auth	`Not authorized to perform this action (must be admin)`
Auth	`Not authorized to update this group (must be admin)`
Auth	`Not authorized to reset group invite link (must be admin)`
Auth	`Not allowed to join this group`
Auth	`Not allowed to leave this group`
Validation	`Identifier is required`
Validation	`At least one participant is required`
Validation	`Invalid action. Must be one of: add, remove, promote, demote, approve, reject`
Identifier	`failed to resolve group from identifier (not a valid JID, code, or link)`
Identifier	`invalid group JID <jid>: <reason>`
Identifier	`not a group JID`
State	`Instance is not connected to WhatsApp`
State	`Group not found or you are not a member of this group`
Invite	`Invite link has been revoked or expired`
Invite	`Invalid invite link or code`
Throttle	`rate limit exceeded (429): wait before creating again`

Create group

Create a new group with initial participants.

List groups

Return all groups for the instance.

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Endpoints

Accepted identifiers

Data structures

`GroupInfo`

`GroupDetail`

`GroupPermissions`

Error envelope

Error reference (summary)

Next

Create group

List groups

​Endpoints

​Accepted identifiers

​Data structures

​GroupInfo

​GroupDetail

​GroupPermissions

​Error envelope

​Error reference (summary)

​Next

Create group

List groups

Endpoints

Accepted identifiers

Data structures

`GroupInfo`

`GroupDetail`

`GroupPermissions`

Error envelope

Error reference (summary)

Next