Ricevere messaggi di gruppo WhatsApp

Qualsiasi messaggio scritto da un partecipante in un gruppo arriva come qualunque altro messaggio WhatsApp in entrata: lo stesso evento whatsapp.received, gli stessi content arm, lo stesso recupero dei media. Due aspetti sono specifici di un gruppo. Il messaggio indica sia il partecipante che lo ha scritto sia il gruppo da cui proviene, e la risposta viene inviata al gruppo anziché a quella persona.

Ricevere messaggi WhatsApp copre le parti non specifiche dei gruppi: ogni content arm, il recupero dei media in entrata e le risposte con citazione.

Cosa contiene un messaggio di gruppo

Un messaggio di gruppo in entrata presenta due indirizzi anziché uno:

• from è il partecipante che lo ha scritto, mai il gruppo. Contiene il suo bsuid (business-scoped user ID), il suo phone_number quando la tua azienda lo conosce, e il suo username e display_name quando pubblica un profilo. Un partecipante che non ha condiviso il proprio numero con te è identificato dal solo bsuid, sufficiente per indirizzargli un messaggio.
• to contiene il tuo numero aziendale e il gruppo. phone_number è il numero che ha ricevuto il messaggio e group_id è il gruppo da cui è arrivato.

group_id compare su to e in nessun altro campo, quindi la sua presenza lì è ciò che distingue un messaggio di gruppo da uno individuale, in entrambe le direzioni. Un messaggio di gruppo non ha contatori: recipient_count, delivered_count e read_count riportano un fan-out in uscita, e un messaggio in entrata non ne ha.

Per leggere il thread di un singolo gruppo, in entrambe le direzioni contemporaneamente, filtra la lista dei messaggi per group_id come mostra Inviare a un gruppo WhatsApp.

Rispondere al gruppo

Un partecipante che scrive nel gruppo apre un'unica finestra di servizio clienti di 24 ore per l'intero gruppo, non una per persona. Finché è aperta, il contenuto libero raggiunge il gruppo; una volta scaduta, serve un template. Indirizza la risposta al gruppo, con l'ID del gruppo in to e senza from. Vedi Inviare a un gruppo WhatsApp.

Scrivere privatamente a quel partecipante è una conversazione separata con una propria finestra, e il messaggio di gruppo non la apre. Un messaggio libero indirizzato al suo numero di telefono o bsuid viene rifiutato con un 422 E15044 a meno che il partecipante non abbia scritto separatamente alla tua azienda nelle ultime 24 ore. Un template lo raggiunge in ogni caso.

Conferma di lettura e reazioni

Entrambe le conferme funzionano su un messaggio di gruppo e richiedono le stesse chiamate di qualsiasi altro messaggio in entrata:

• Segna come letto con l'ID del messaggio stesso. Nulla cambia nella chiamata per un gruppo.
• Reagisci con un emoji. La reazione viene inviata al gruppo, quindi ogni partecipante la vede. Un gruppo non attivo rifiuta la modifica con un 409 E15047, l'unico rifiuto che una reazione a un messaggio di gruppo presenta rispetto a una reazione individuale.

Il webhook

whatsapp.received trasporta un messaggio di gruppo nella stessa struttura di qualsiasi altro, con il gruppo su 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
  }
}

Leggi data.to.group_id per instradare il messaggio al thread del gruppo e data.from per attribuirlo a un partecipante. Un subscriber che indicizza le conversazioni solo su from separa ogni partecipante di un gruppo in un thread distinto e perde il gruppo.

Non esiste un evento per il gruppo stesso. L'ingresso o l'uscita di un partecipante, una modifica del nome o un messaggio fissato non producono alcun webhook, quindi la composizione del gruppo si legge anziché riceverla in push: apri il gruppo nella pagina Groups, oppure recuperalo come mostra Gestione dei gruppi WhatsApp.

Passaggi successivi

• Inviare a un gruppo WhatsApp: indirizzare il gruppo, cosa serve e le ricevute per partecipante
• Gestione dei gruppi WhatsApp: creare un gruppo tramite API, link di invito, richieste di partecipazione e messaggi fissati
• Gruppi WhatsApp: a cosa serve un gruppo e quali limiti impone WhatsApp
• Ricezione dei messaggi WhatsApp: ogni tipo di contenuto, media e risposte con citazione
• Business-scoped user ID: indirizzare un partecipante di cui non si ha il numero di telefono