Groupes WhatsApp

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`	`groups:read`
GET	`/groups/{id}`	`groups:read`
GET	`/groups/{id}/members`	`groups:read`
GET	`/groups/{id}/messages`	`groups:read`
GET	`/groups/{id}/events`	`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 "https://app.whatsetter.com/api/v1/groups?status=active&limit=25" \
  -H "Authorization: Bearer ws_live_…"

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();

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"]

{
  "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 :

{
  "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 "https://app.whatsetter.com/api/v1/groups/66f1a2b3c4d5e6f7a8b9c101/members?status=active&limit=100" \
  -H "Authorization: Bearer ws_live_…"

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();

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"]

{
  "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 "https://app.whatsetter.com/api/v1/groups/66f1a2b3c4d5e6f7a8b9c101/messages?since=2026-09-18T00:00:00Z&from_agent=false" \
  -H "Authorization: Bearer ws_live_…"

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();

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"]

{
  "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 "https://app.whatsetter.com/api/v1/groups/66f1a2b3c4d5e6f7a8b9c101/events?type=join&since=2026-09-18T00:00:00Z" \
  -H "Authorization: Bearer ws_live_…"

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();

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"]

{
  "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`.