Groups

Manage WhatsApp groups through the Wappfy API. You can create groups, manage participants, handle invite links, and more. All group endpoints are scoped to a specific instance:

/api/instances/{instanceId}/groups/...

Create a Group

Create a new WhatsApp group with initial participants.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/groups \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Project Alpha",
    "participants": [
      "5511999998888@s.whatsapp.net",
      "5511888887777@s.whatsapp.net"
    ]
  }'

const response = await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/groups",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Project Alpha",
      participants: [
        "5511999998888@s.whatsapp.net",
        "5511888887777@s.whatsapp.net",
      ],
    }),
  }
);

const group = await response.json();
console.log(group.data.group_id);

Response:

{
  "data": {
    "group_id": "120363012345678901@g.us",
    "name": "Project Alpha",
    "participants": [
      {
        "id": "5511999998888@s.whatsapp.net",
        "is_admin": false
      },
      {
        "id": "5511888887777@s.whatsapp.net",
        "is_admin": false
      }
    ]
  }
}

List Groups

Retrieve all groups the instance is a member of.

curl https://api.wappfy.io/api/instances/inst_abc123/groups \
  -H "X-Api-Key: YOUR_API_KEY"

const response = await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/groups",
  {
    headers: { "X-Api-Key": "YOUR_API_KEY" },
  }
);

const { data } = await response.json();
console.log(`Found ${data.length} groups`);

Response:

{
  "data": [
    {
      "group_id": "120363012345678901@g.us",
      "name": "Project Alpha",
      "participant_count": 5
    },
    {
      "group_id": "120363098765432109@g.us",
      "name": "Support Team",
      "participant_count": 12
    }
  ]
}

Get Group Info

Fetch detailed information about a specific group.

curl https://api.wappfy.io/api/instances/inst_abc123/groups/120363012345678901@g.us \
  -H "X-Api-Key: YOUR_API_KEY"

Response:

{
  "data": {
    "group_id": "120363012345678901@g.us",
    "name": "Project Alpha",
    "description": "Team workspace for Project Alpha",
    "owner": "5511999998888@s.whatsapp.net",
    "created_at": "2026-01-15T10:00:00Z",
    "participants": [
      {
        "id": "5511999998888@s.whatsapp.net",
        "is_admin": true,
        "is_super_admin": true
      },
      {
        "id": "5511888887777@s.whatsapp.net",
        "is_admin": false,
        "is_super_admin": false
      }
    ]
  }
}

Update a Group

Update the group name or description. You must be a group admin to perform this action.

curl -X PATCH https://api.wappfy.io/api/instances/inst_abc123/groups/120363012345678901@g.us \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Project Alpha v2",
    "description": "Updated workspace for Project Alpha"
  }'

Only group admins can update the group name and description. If the instance is not an admin, this will return a 403 error.

Leave a Group

Remove the instance from a group.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/groups/120363012345678901@g.us/leave \
  -H "X-Api-Key: YOUR_API_KEY"

After leaving a group, you will need an invite link or another admin to add you back.

Participants

List Participants

Get all participants of a group.

curl https://api.wappfy.io/api/instances/inst_abc123/groups/120363012345678901@g.us/participants \
  -H "X-Api-Key: YOUR_API_KEY"

Response:

{
  "data": [
    {
      "id": "5511999998888@s.whatsapp.net",
      "is_admin": true,
      "is_super_admin": true
    },
    {
      "id": "5511888887777@s.whatsapp.net",
      "is_admin": false,
      "is_super_admin": false
    },
    {
      "id": "5511777776666@s.whatsapp.net",
      "is_admin": true,
      "is_super_admin": false
    }
  ]
}

Add Participants

Add one or more participants to a group. You must be a group admin.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/groups/120363012345678901@g.us/participants \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participants": [
      "5511666665555@s.whatsapp.net",
      "5511555554444@s.whatsapp.net"
    ]
  }'

await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/groups/120363012345678901@g.us/participants",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      participants: [
        "5511666665555@s.whatsapp.net",
        "5511555554444@s.whatsapp.net",
      ],
    }),
  }
);

Remove Participants

Remove one or more participants from a group. You must be a group admin.

curl -X DELETE https://api.wappfy.io/api/instances/inst_abc123/groups/120363012345678901@g.us/participants \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participants": [
      "5511666665555@s.whatsapp.net"
    ]
  }'

Invite Codes

Get Invite Code

Generate or retrieve the group’s invite link. You must be a group admin.

curl https://api.wappfy.io/api/instances/inst_abc123/groups/120363012345678901@g.us/invite-code \
  -H "X-Api-Key: YOUR_API_KEY"

Response:

{
  "data": {
    "invite_code": "https://chat.whatsapp.com/AbCdEfGhIjKlMn"
  }
}

Join via Invite Code

Join a group using an invite code.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/groups/join \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invite_code": "AbCdEfGhIjKlMn"
  }'

Pass only the code portion, not the full URL. For https://chat.whatsapp.com/AbCdEfGhIjKlMn, pass AbCdEfGhIjKlMn.

Sending Messages to Groups

To send a message to a group, use the standard send message endpoint with the group’s chat ID:

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "120363012345678901@g.us",
    "type": "text",
    "text": "Hello team!"
  }'

Group chat IDs always end with @g.us.

Endpoint Reference

Method	Endpoint	Description
`POST`	`/api/instances/{id}/groups`	Create a new group
`GET`	`/api/instances/{id}/groups`	List all groups
`GET`	`/api/instances/{id}/groups/{groupId}`	Get group info
`PATCH`	`/api/instances/{id}/groups/{groupId}`	Update group name/description
`POST`	`/api/instances/{id}/groups/{groupId}/leave`	Leave a group
`GET`	`/api/instances/{id}/groups/{groupId}/participants`	List participants
`POST`	`/api/instances/{id}/groups/{groupId}/participants`	Add participants
`DELETE`	`/api/instances/{id}/groups/{groupId}/participants`	Remove participants
`GET`	`/api/instances/{id}/groups/{groupId}/invite-code`	Get invite code
`POST`	`/api/instances/{id}/groups/join`	Join via invite code

Error Handling

Status Code	Description
`403`	You are not an admin of this group.
`404`	Group not found or instance is not a member.
`409`	Participant is already in the group (on add) or not in the group (on remove).
`422`	Invalid participant format. Use `{phone}@s.whatsapp.net`.

Getting Started

Guides

Groups

Groups

Create a Group

List Groups

Get Group Info

Update a Group

Leave a Group

Participants

List Participants

Add Participants

Remove Participants

Invite Codes

Get Invite Code

Join via Invite Code

Sending Messages to Groups

Endpoint Reference

Error Handling

​Groups

​Create a Group

​List Groups

​Get Group Info

​Update a Group

​Leave a Group

​Participants

​List Participants

​Add Participants

​Remove Participants

​Invite Codes

​Get Invite Code

​Join via Invite Code

​Sending Messages to Groups

​Endpoint Reference

​Error Handling

Groups

Create a Group

List Groups

Get Group Info

Update a Group

Leave a Group

Participants

List Participants

Add Participants

Remove Participants

Invite Codes

Get Invite Code

Join via Invite Code

Sending Messages to Groups

Endpoint Reference

Error Handling