Recibir mensajes de grupo de WhatsApp

Todo lo que un participante escribe en un grupo llega igual que cualquier otro mensaje entrante de WhatsApp: el mismo evento whatsapp.received, los mismos brazos de contenido, la misma descarga de medios. Dos cosas son particulares de un grupo. El mensaje nombra tanto al participante que lo escribió como al grupo por el que llegó, y tu respuesta va al grupo en lugar de a esa persona.

Recibir mensajes de WhatsApp cubre las partes que no son específicas de grupo: cada brazo de contenido, descarga de medios entrantes y respuestas citadas.

Qué lleva un mensaje de grupo

Un mensaje de grupo entrante se lee con dos direcciones en lugar de una:

• from es el participante que lo escribió, nunca el grupo. Lleva su bsuid (identificador de usuario en el ámbito del negocio), su phone_number cuando tu negocio lo conoce, y su username y display_name cuando publican un perfil. Un participante que no ha compartido su número contigo se identifica solo por el bsuid, que es suficiente para dirigirle mensajes.
• to lleva tu número de negocio y el grupo. phone_number es el número que recibió el mensaje, y group_id es el grupo por el que llegó.

group_id aparece en to y en ningún otro lugar, así que su presencia ahí es lo que distingue un mensaje de grupo de uno individual, en cualquier dirección. Un mensaje de grupo no lleva contadores: recipient_count, delivered_count y read_count reportan un envío saliente a múltiples destinatarios, y un mensaje entrante no tiene ninguno.

Para leer el hilo de un grupo en ambas direcciones a la vez, filtra la lista de mensajes por group_id como muestra Enviar a un grupo de WhatsApp.

Responder al grupo

Un participante que escribe en el grupo abre una única ventana de servicio al cliente de 24 horas para todo el grupo, no una por persona. Mientras esté abierta, el contenido libre llega al grupo; cuando vence, lo hace una plantilla. Dirige la respuesta al grupo, con el ID de grupo en to y sin from. Consulta Enviar a un grupo de WhatsApp.

Escribir a ese participante en privado es una conversación aparte con su propia ventana, y el mensaje de grupo no la abre. Un mensaje libre dirigido a su número de teléfono o bsuid se rechaza con un 422 E15044 a menos que esa persona haya escrito por separado a tu negocio en las últimas 24 horas. Una plantilla sí le llega en cualquier caso.

Confirmar y reaccionar

Ambas confirmaciones funcionan en un mensaje de grupo y usan las mismas llamadas que en cualquier otro mensaje entrante:

• Marcarlo como leído con el ID del propio mensaje. Nada de la llamada cambia para un grupo.
• Reaccionar con un emoji. La reacción va al grupo, así que todos los participantes la ven. Un grupo que no está activo rechaza el cambio con un 409 E15047, que es el único rechazo que tiene una reacción a un mensaje de grupo y que una reacción individual no tiene.

El webhook

whatsapp.received lleva un mensaje de grupo en la misma estructura que cualquier otro, con el grupo en 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
  }
}

Lee data.to.group_id para enrutar el mensaje al hilo del grupo, y data.from para atribuirlo a un participante. Un suscriptor que indexa conversaciones solo por from mete a cada participante de un grupo en un hilo separado y pierde el grupo.

No existe un evento para el grupo en sí. Alguien que se une o se va, un cambio de nombre o un mensaje fijado no produce ningún webhook, así que la membresía de un grupo se consulta en lugar de recibirse: abre el grupo en la página Groups, o consúltalo como muestra Gestionar grupos de WhatsApp.

Siguientes pasos

• Enviar a un grupo de WhatsApp: dirigirse al grupo, qué se necesita y sus recibos por participante
• Gestionar grupos de WhatsApp: crear un grupo a través de la API, enlaces de invitación, solicitudes de ingreso y mensajes fijados
• Grupos de WhatsApp: para qué sirve un grupo y qué limita WhatsApp
• Recibir mensajes de WhatsApp: todos los tipos de contenido, medios y respuestas citadas
• Identificadores de usuario con alcance de negocio: dirigirte a un participante cuyo número de teléfono no tienes