# WhatsApp groups

> Read your tracked WhatsApp groups: details, members, transcript and join or leave events, with the 500-group tracking cap explained.

Source: https://docs.whatsetter.com/developers/guides/groups/

A group is a WhatsApp group or community your agent is a member of and that you chose to track in the dashboard. The API exposes tracked groups read-only: the group itself, its members, its messages and its membership events.

## Endpoints

| Method | Path | Scope |
|---|---|---|
| GET | [`/groups`](/api-reference/operations/listgroups/) | `groups:read` |
| GET | [`/groups/{id}`](/api-reference/operations/getgroup/) | `groups:read` |
| GET | [`/groups/{id}/members`](/api-reference/operations/listgroupmembers/) | `groups:read` |
| GET | [`/groups/{id}/messages`](/api-reference/operations/listgroupmessages/) | `groups:read` |
| GET | [`/groups/{id}/events`](/api-reference/operations/listgroupevents/) | `groups:read` |

## What "tracked" means

WhatSetter only stores what happens in the groups you track from the dashboard's groups page. A tracked group is a group with status `active`: its messages are recorded, its members are synced, and the agent can reply in it according to its mode. Paused, archived or left groups keep their history but stop being counted.

A workspace can track up to **500 active groups**. Tracking more from the dashboard is refused until you pause or archive some.

## List groups

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/groups?status=active&limit=25" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/groups?status=active&limit=25', {
  headers: { Authorization: 'Bearer ws_live_…' },
});
const { data: groups, pagination } = await res.json();
```

**Python**

```python
import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/groups",
    params={"status": "active", "limit": 25},
    headers={"Authorization": "Bearer ws_live_…"},
)
groups = r.json()["data"]
```

```json
{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c101",
      "whatsapp_id": "120363012345678901@g.us",
      "name": "Webinar 24 Sept",
      "description": "Questions before the live session",
      "participants_count": 148,
      "messages_count": 912,
      "status": "active",
      "ai_enabled": true,
      "invite_url": "https://chat.whatsapp.com/…",
      "campaign_id": "acme-community-1-cd34",
      "created_at": "2026-09-01T09:00:00.000Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": "66f1a2b3c4d5e6f7a8b9c101" }
}
```

Filters: `status` (`active`, `paused`, `archived`, `left`) and `community_id` (only groups of one WhatsApp Community, the `community.id` of a group). Newest first.

## Get one group

`GET /groups/{id}` returns the same fields plus the details:

```json
{
  "data": {
    "id": "66f1a2b3c4d5e6f7a8b9c101",
    "whatsapp_id": "120363012345678901@g.us",
    "name": "Webinar 24 Sept",
    "description": "Questions before the live session",
    "participants_count": 148,
    "messages_count": 912,
    "status": "active",
    "ai_enabled": true,
    "invite_url": "https://chat.whatsapp.com/…",
    "campaign_id": "acme-community-1-cd34",
    "created_at": "2026-09-01T09:00:00.000Z",
    "is_admin": true,
    "ai_reply_mode": "mentions_only",
    "intent": "webinar",
    "community": { "id": "120363098765432101@g.us", "name": "Acme Community", "role": "sub" },
    "sync_status": "ready",
    "synced_at": "2026-09-18T22:00:00.000Z",
    "picture_url": "https://pps.whatsapp.net/…",
    "updated_at": "2026-09-18T22:00:00.000Z"
  }
}
```

| Field | Meaning |
|---|---|
| `is_admin` | Whether the connected number is an admin of the group. |
| `ai_reply_mode` | `mentions_only` or `all_messages`. |
| `intent` | `community`, `webinar` or `broadcast`. |
| `community` | The WhatsApp Community the group belongs to, `null` for a standalone group. `role: "announce"` is the community's announcements group, `sub` a regular sub-group. |
| `sync_status` | State of the message-history import: `idle`, `pending`, `syncing`, `ready`, `error`. |
| `picture_url` | An expiring WhatsApp CDN link to the group picture. Fetch it when you need it, do not store it. |

## Members

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/groups/66f1a2b3c4d5e6f7a8b9c101/members?status=active&limit=100" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch(
  'https://app.whatsetter.com/api/v1/groups/66f1a2b3c4d5e6f7a8b9c101/members?status=active&limit=100',
  { headers: { Authorization: 'Bearer ws_live_…' } },
);
const { data: members, pagination } = await res.json();
```

**Python**

```python
import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/groups/66f1a2b3c4d5e6f7a8b9c101/members",
    params={"status": "active", "limit": 100},
    headers={"Authorization": "Bearer ws_live_…"},
)
members = r.json()["data"]
```

```json
{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c111",
      "phone": "33612345678",
      "name": "Julien",
      "role": "member",
      "status": "active",
      "joined_at": "2026-09-02T10:15:00.000Z",
      "left_at": null,
      "joined_source": "event",
      "messages_count": 12
    }
  ],
  "pagination": { "has_more": false, "next_cursor": "66f1a2b3c4d5e6f7a8b9c111" }
}
```

`role` is `superadmin`, `admin` or `member`. `status` becomes `left` once the person leaves. `phone` is `null` when WhatsApp only exposed an anonymous id for that member.

## Messages

The group transcript, newest first. `since` and `until` bound the window, `sender` keeps one member's messages (international digits), `from_agent=true` keeps what WhatSetter sent through the connected number, `from_agent=false` keeps only members' messages.

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/groups/66f1a2b3c4d5e6f7a8b9c101/messages?since=2026-09-18T00:00:00Z&from_agent=false" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch(
  'https://app.whatsetter.com/api/v1/groups/66f1a2b3c4d5e6f7a8b9c101/messages?since=2026-09-18T00:00:00Z&from_agent=false',
  { headers: { Authorization: 'Bearer ws_live_…' } },
);
const { data: messages, pagination } = await res.json();
```

**Python**

```python
import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/groups/66f1a2b3c4d5e6f7a8b9c101/messages",
    params={"since": "2026-09-18T00:00:00Z", "from_agent": "false"},
    headers={"Authorization": "Bearer ws_live_…"},
)
messages = r.json()["data"]
```

```json
{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c121",
      "whatsapp_message_id": "false_120363012345678901@g.us_3EB0C8F2A1D4B5E6F7A8",
      "sender": { "phone": "33612345678", "name": "Julien" },
      "from_agent": false,
      "ai_generated": false,
      "text": "Will the replay be available?",
      "type": "USER_MESSAGE",
      "is_mention": true,
      "has_media": false,
      "media_type": null,
      "sent_at": "2026-09-18T18:02:11.000Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": "66f1a2b3c4d5e6f7a8b9c121" }
}
```

`sender` is `null` when neither a phone nor a name is known. `ai_generated` is a subset of `from_agent`: `true` only for AI replies, `false` for manual replies sent from the dashboard. Media is flagged with `has_media` and `media_type` (`image`, `video`, `audio`, `document`…) but never linked.

## Events

Joins and leaves, as observed from live WhatsApp events and sync passes. Filters: `type` (`join`, `leave`), `since`, `until`.

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/groups/66f1a2b3c4d5e6f7a8b9c101/events?type=join&since=2026-09-18T00:00:00Z" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch(
  'https://app.whatsetter.com/api/v1/groups/66f1a2b3c4d5e6f7a8b9c101/events?type=join&since=2026-09-18T00:00:00Z',
  { headers: { Authorization: 'Bearer ws_live_…' } },
);
const { data: events, pagination } = await res.json();
```

**Python**

```python
import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/groups/66f1a2b3c4d5e6f7a8b9c101/events",
    params={"type": "join", "since": "2026-09-18T00:00:00Z"},
    headers={"Authorization": "Bearer ws_live_…"},
)
events = r.json()["data"]
```

```json
{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c131",
      "type": "join",
      "phone": "33612345678",
      "name": "Julien",
      "occurred_at": "2026-09-18T09:30:00.000Z",
      "source": "event",
      "actor_phone": "33698765432"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": "66f1a2b3c4d5e6f7a8b9c131" }
}
```

`source` says how the event was observed: `event` (live), `sync_detected`, `backfill` or `webhook_replay`. `actor_phone` is the admin who added or removed the member, when WhatsApp reported one.

## Errors you will meet

| HTTP | `code` | When |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Key absent, unknown or revoked. |
| 403 | `insufficient_scope` | The key lacks `groups:read`. |
| 404 | `not_found` | Unknown group, or a group of another workspace. |
| 422 | `validation_error` | Unknown `status` or `type`, bad `since` or `until`, `sender` not a phone, `from_agent` not `true` or `false`, invalid cursor. |
| 429 | `rate_limited` | Too many requests this minute. Honor `Retry-After`. |

## Related

- [WhatsApp groups in the dashboard](/dashboard/groups/)
- [Conversations](/developers/guides/conversations/)
- [MCP server](/developers/mcp/)
