# Groupes WhatsApp

> Lire tes groupes WhatsApp suivis : détails, membres, transcription et événements d'arrivée ou de départ, avec le plafond de 500 groupes expliqué.

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

Un groupe, c'est un groupe ou une communauté WhatsApp dont ton agent est membre et que tu as choisi de suivre dans le dashboard. L'API expose les groupes suivis en lecture seule : le groupe lui-même, ses membres, ses messages et ses événements d'adhésion.

## Endpoints

| Méthode | Chemin | 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` |

## Ce que « suivi » veut dire

WhatSetter ne stocke que ce qui se passe dans les groupes que tu suis depuis la page des groupes du dashboard. Un groupe suivi est un groupe au statut `active` : ses messages sont enregistrés, ses membres synchronisés, et l'agent peut y répondre selon son mode. Les groupes en pause, archivés ou quittés gardent leur historique mais ne comptent plus.

Un espace de travail peut suivre jusqu'à **500 groupes actifs**. En suivre davantage depuis le dashboard est refusé tant que tu n'en mets pas en pause ou n'en archives pas.

## Lister les groupes

**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": "Webinaire 24 sept",
      "description": "Questions avant le live",
      "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" }
}
```

Filtres : `status` (`active`, `paused`, `archived`, `left`) et `community_id` (seulement les groupes d'une communauté WhatsApp, le `community.id` d'un groupe). Les plus récents d'abord.

## Lire un groupe

`GET /groups/{id}` renvoie les mêmes champs plus les détails :

```json
{
  "data": {
    "id": "66f1a2b3c4d5e6f7a8b9c101",
    "whatsapp_id": "120363012345678901@g.us",
    "name": "Webinaire 24 sept",
    "description": "Questions avant le live",
    "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": "Communauté Acme", "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"
  }
}
```

| Champ | Signification |
|---|---|
| `is_admin` | Si le numéro connecté est administrateur du groupe. |
| `ai_reply_mode` | `mentions_only` ou `all_messages`. |
| `intent` | `community`, `webinar` ou `broadcast`. |
| `community` | La communauté WhatsApp à laquelle le groupe appartient, `null` pour un groupe isolé. `role: "announce"` est le groupe d'annonces de la communauté, `sub` un sous-groupe classique. |
| `sync_status` | État de l'import de l'historique : `idle`, `pending`, `syncing`, `ready`, `error`. |
| `picture_url` | Un lien CDN WhatsApp à durée limitée vers la photo du groupe. Récupère-la quand tu en as besoin, ne la stocke pas. |

## Membres

**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` vaut `superadmin`, `admin` ou `member`. `status` passe à `left` quand la personne quitte le groupe. `phone` vaut `null` quand WhatsApp n'a exposé qu'un identifiant anonyme pour ce membre.

## Messages

La transcription du groupe, du plus récent au plus ancien. `since` et `until` bornent la fenêtre, `sender` garde les messages d'un seul membre (chiffres internationaux), `from_agent=true` garde ce que WhatSetter a envoyé via le numéro connecté, `from_agent=false` garde seulement les messages des membres.

**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": "Le replay sera disponible ?",
      "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` vaut `null` quand ni téléphone ni nom ne sont connus. `ai_generated` est un sous-ensemble de `from_agent` : `true` seulement pour les réponses de l'IA, `false` pour les réponses manuelles envoyées depuis le dashboard. Les médias sont signalés par `has_media` et `media_type` (`image`, `video`, `audio`, `document`…) mais jamais liés.

## Événements

Arrivées et départs, observés depuis les événements WhatsApp en direct et les passes de synchronisation. Filtres : `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` dit comment l'événement a été observé : `event` (en direct), `sync_detected`, `backfill` ou `webhook_replay`. `actor_phone` est l'administrateur qui a ajouté ou retiré le membre, quand WhatsApp l'a signalé.

## Les erreurs que tu rencontreras

| HTTP | `code` | Quand |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Clé absente, inconnue ou révoquée. |
| 403 | `insufficient_scope` | La clé n'a pas `groups:read`. |
| 404 | `not_found` | Groupe inconnu, ou groupe d'un autre espace de travail. |
| 422 | `validation_error` | `status` ou `type` inconnu, `since` ou `until` invalide, `sender` qui n'est pas un téléphone, `from_agent` différent de `true` ou `false`, curseur invalide. |
| 429 | `rate_limited` | Trop de requêtes cette minute. Respecte `Retry-After`. |

## Voir aussi

- [Groupes WhatsApp dans le dashboard](/fr/dashboard/groups/)
- [Conversations](/fr/developers/guides/conversations/)
- [Serveur MCP](/fr/developers/mcp/)
