Recevoir des messages de groupe WhatsApp

Tout ce qu'un participant écrit dans un groupe arrive comme n'importe quel autre message WhatsApp entrant : le même événement whatsapp.received, les mêmes bras de contenu, la même récupération de média. Deux choses sont propres à un groupe. Le message nomme à la fois le participant qui l'a écrit et le groupe par lequel il est passé, et votre réponse est envoyée au groupe plutôt qu'à cette personne.

Recevoir des messages WhatsApp couvre les parties qui ne sont pas propres aux groupes : chaque bras de contenu, la récupération des médias entrants, et les réponses citées.

Ce que transporte un message de groupe

Un message de groupe entrant est restitué avec deux adresses au lieu d'une :

• from est le participant qui l'a écrit, jamais le groupe. Il porte son bsuid (identifiant utilisateur à portée business), son phone_number quand votre entreprise le connaît, ainsi que ses username et display_name quand il publie un profil. Un participant qui n'a pas partagé son numéro avec vous est identifié par le bsuid seul, ce qui suffit pour lui envoyer un message.
• to porte le numéro de votre entreprise et le groupe. phone_number est le numéro qui a reçu le message, et group_id est le groupe par lequel il est arrivé.

group_id apparaît sur to et nulle part ailleurs ; sa présence à cet endroit est ce qui distingue un message de groupe d'un message individuel, dans les deux sens. Un message de groupe ne porte pas de compteurs : recipient_count, delivered_count et read_count rapportent une diffusion sortante, et un message entrant n'en a pas.

Pour lire le fil d'un groupe dans les deux sens à la fois, filtrez la liste de messages par group_id comme le montre Envoyer à un groupe WhatsApp.

Répondre au groupe

Un participant qui écrit dans le groupe ouvre une seule fenêtre de service client de 24 heures pour l'ensemble du groupe, et non une par personne. Tant qu'elle est ouverte, du contenu libre atteint le groupe ; une fois expirée, un template est nécessaire. Adressez la réponse au groupe, avec l'identifiant du groupe dans to et sans from. Voir Envoyer à un groupe WhatsApp.

Écrire à ce participant en privé est une conversation distincte avec sa propre fenêtre, et le message de groupe ne l'ouvre pas. Un message libre adressé à son numéro de téléphone ou à son bsuid est refusé avec une 422 E15044 sauf s'il a séparément contacté votre entreprise dans les dernières 24 heures. Un template lui parvient dans tous les cas.

Accusés de réception et réactions

Les deux types d'accusé fonctionnent sur un message de groupe et utilisent les mêmes appels que sur tout autre message entrant :

• Marquer comme lu avec l'identifiant du message lui-même. Rien dans l'appel ne change pour un groupe.
• Réagir avec un emoji. La réaction est envoyée au groupe, donc chaque participant la voit. Un groupe qui n'est pas actif refuse la modification avec une 409 E15047, ce qui est le seul refus qu'une réaction sur un message de groupe peut recevoir et qu'une réaction individuelle ne reçoit pas.

Le webhook

whatsapp.received transporte un message de groupe dans la même enveloppe que tout autre message, avec le groupe sur to :

{
  "type": "whatsapp.received",
  "timestamp": "2026-09-15T14:05:41.204Z",
  "data": {
    "whatsapp_id": "wam_01kya1b3xdq7fe8m2v5t9rncgs",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+15550002222", "bsuid": "US.AbC1", "display_name": "Dana Reyes" },
    "to": { "phone_number": "+15550001111", "group_id": "wag_01krdgeqcxet5s7t44vh8rt9mg" },
    "text": { "body": "Got it, thanks." },
    "tags": null,
    "metadata": null
  }
}

Lisez data.to.group_id pour diriger le message vers le fil du groupe, et data.from pour l'attribuer à un participant. Un abonné qui indexe les conversations sur from seul place chaque participant d'un groupe dans un fil distinct et perd le groupe.

Il n'existe aucun événement pour le groupe lui-même. Une arrivée ou un départ de membre, un changement de nom ou une épingle ne produit aucun webhook. L'appartenance au groupe se lit donc au lieu d'être poussée : ouvrez le groupe sur la page Groups, ou récupérez-le comme le montre Gestion des groupes WhatsApp.

Étapes suivantes

• Envoyer à un groupe WhatsApp : adresser le groupe, les conditions requises et les accusés de réception par participant
• Gestion des groupes WhatsApp : créer un groupe via l'API, liens d'invitation, demandes d'adhésion et épingles
• Groupes WhatsApp : à quoi sert un groupe et ce que WhatsApp limite
• Réception des messages WhatsApp : chaque type de contenu, médias et réponses citées
• Identifiants utilisateur à portée business : adresser un participant dont vous n'avez pas le numéro de téléphone