Notificaciones de grupos

Last update: 4 days ago by Irais Aguirre

Resumen para integración
Entrega: WhatsApp → Concepto Móvil → POST a la URL de tu webhook (la que compartes con nuestro equipo de Operaciones), con un JSON en el cuerpo.
Formato: el objeto value de Meta sin metadata ni messaging_product (ver Webhook).
Identificar al usuario: from/recipient_id o, si no llega, el BSUID.
Tipos en esta página: group_create, group_delete, group_participants_add, group_participants_remove, group_join_request_created, group_join_request_revoked, group_settings_update, group_suspend, group_suspend_cleared (valores de type) y estatus de mensajes enviados a un grupo

Eventos de los grupos de tu número: creación y eliminación de grupos, cambios de participantes, solicitudes para unirse, configuración y suspensión del grupo. Para crear y administrar grupos, consulta Grupos.

Estructura general

Estructura común a todos los eventos de grupos.

Estructura

Campos de Estructura general:

Nombre	Descripción	Tipo
groups	Lista de eventos de grupo. Cada objeto trae al menos `timestamp`, `group_id` y `type`; los demás campos dependen del tipo de evento (ver Ejemplos).	Lista objetos

Valores del campo type:

Valor	Evento
group_create	Resultado de la creación de un grupo.
group_delete	Resultado de la eliminación de un grupo.
group_participants_add	Un usuario se unió al grupo (por ejemplo, mediante el enlace de invitación).
group_participants_remove	Se eliminó a uno o más participantes, o un participante abandonó el grupo (`initiated_by` indica quién lo originó).
group_join_request_created	Un usuario solicitó unirse a un grupo con aprobación requerida.
group_join_request_revoked	Un usuario canceló su solicitud para unirse.
group_settings_update	Resultado de la actualización del asunto, la descripción o la foto de perfil del grupo.
group_suspend	WhatsApp suspendió el grupo.
group_suspend_cleared	Se retiró la suspensión del grupo.

Nota: los objetos de participante (added_participants, removed_participants, failed_participants) y los eventos de solicitud de unión identifican al usuario con las mismas reglas que las notificaciones de mensajes: user_id (BSUID) siempre se incluye, wa_id se incluye solo cuando el número de teléfono está disponible, parent_user_id se incluye solo si la empresa tiene portafolios vinculados, y username se incluye solo si el usuario tiene uno. Consulta Nombres de usuario y BSUID. Por brevedad, algunos ejemplos a continuación muestran solo wa_id o input.

Crear grupo

El campo type es "group_create".

Ejemplo

Ejemplo completo de Crear grupo:

Creación exitosa de un grupo

{
    "groups": [
        {
            "timestamp": "TIMESTAMP",
            "group_id": "GROUP_ID",
            "type": "group_create",
            "request_id": "REQUEST_ID",
            "subject": "test invite link",
            "invite_link": "https://chat.whatsapp.com/LINK_ID",
            "join_approval_mode": "JOIN_APPROVAL_MODE"
        }
    ]
}

Error al crear un grupo

{
    "groups": [
        {
            "timestamp": "TIMESTAMP",
            "type": "group_create",
            "subject": "GROUP_SUBJECT",
            "description": "GROUP_DESCRIPTION",
            "request_id": "REQUEST_ID",
            "group_id": "GROUP_ID",
            "errors": [
                {
                    "code": "ERROR_CODE",
                    "message": "ERROR_MESSAGE",
                    "title": "ERROR_TITLE",
                    "error_data": {
                        "details": "ERROR_DETAILS"
                    }
                }
            ]
        }
    ]
}

Eliminar grupo

El campo type es "group_delete".

Ejemplo

Ejemplo completo de Eliminar grupo:

{
    "groups": [
        {
            "timestamp": "TIMESTAMP",
            "group_id": "GROUP_ID",
            "type": "group_delete",
            "request_id": "REQUEST_ID",
            "errors": [
                {
                    "code": "ERROR_CODE",
                    "message": "ERROR_MESSAGE",
                    "title": "ERROR_TITLE",
                    "error_data": {
                        "details": "ERROR_DETAILS"
                    }
                }
            ]
        }
    ]
}

errors solo se incluye si la eliminación falló.

Un usuario se une al grupo mediante un enlace de invitación

El campo type es "group_participants_add".

Ejemplo

Ejemplo completo de Un usuario se une al grupo mediante un enlace de invitación:

{
    "groups": [
        {
            "timestamp": "TIMESTAMP",
            "group_id": "GROUP_ID",
            "type": "group_participants_add",
            "reason": "invite_link",
            "added_participants": [
                {
                    "wa_id": "WHATSAPP_ID",
                    "user_id": "BSUID",
                    "parent_user_id": "PARENT_BSUID",
                    "username": "USERNAME"
                }
            ]
        }
    ]
}

user_id siempre se incluye; wa_id, parent_user_id y username se incluyen solo en los casos descritos en la nota anterior.

El usuario acepta o cancela la solicitud para unirse

Aplica a grupos con join_approval_mode en modo de aprobación requerida. El campo type indica el evento:

Solicitud creada: type es group_join_request_created.
Solicitud cancelada: type es group_join_request_revoked.

Ejemplo

Ejemplo completo de El usuario acepta o cancela la solicitud para unirse:

{
    "groups": [
        {
            "timestamp": "WEBHOOK_TRIGGER_TIMESTAMP",
            "group_id": "GROUP_ID",
            "type": "GROUP_REQUEST_TYPE",
            "reason": "REASON_FOR_REQUEST_OUTCOME",
            "join_request_id": "JOIN_REQUEST_ID",
            "wa_id": "WHATSAPP_USER_ID"
        }
    ]
}

Solicitud para unirse aprobada

Cuando la solicitud se aprueba (manual o automáticamente), se envía además un evento group_participants_add con reason: "invite_link":

{
    "groups": [
        {
            "timestamp": "WEBHOOK_TRIGGER_TIMESTAMP",
            "group_id": "GROUP_ID",
            "type": "group_participants_add",
            "reason": "invite_link",
            "added_participants": [
                {
                    "input": "WHATSAPP_USER_PHONE_NUMBER",
                    "wa_id": "WHATSAPP_USER_ID"
                }
            ]
        }
    ]
}

Eliminar participantes del grupo

Se activa un evento group_participants_remove cuando el negocio elimina uno o más participantes del grupo (initiated_by: "business").

Ejemplo

Ejemplo completo de Eliminar participantes del grupo:

Eliminación exitosa de participantes

{
    "groups": [
        {
            "timestamp": "TIMESTAMP",
            "group_id": "GROUP_ID",
            "type": "group_participants_remove",
            "request_id": "REQUEST_ID",
            "removed_participants": [
                {
                    "input": "PHONE_NUMBER or WHATSAPP_ID"
                }
            ],
            "initiated_by": "business"
        }
    ]
}

Eliminación parcial de participantes

{
    "groups": [
        {
            "timestamp": "TIMESTAMP",
            "group_id": "GROUP_ID",
            "type": "group_participants_remove",
            "request_id": "REQUEST_ID",
            "initiated_by": "business",
            "removed_participants": [
                {
                    "input": "PHONE_NUMBER or WHATSAPP_ID"
                }
            ],
            "failed_participants": [
                {
                    "input": "PHONE_NUMBER or WHATSAPP_ID",
                    "errors": [
                        {
                            "code": "ERROR_CODE",
                            "message": "ERROR_MESSAGE",
                            "title": "ERROR_TITLE",
                            "error_data": {
                                "details": "ERROR_DETAILS"
                            }
                        }
                    ]
                }
            ],
            "errors": [
                {
                    "code": "ERROR_CODE",
                    "message": "Failed to remove some participants from the group",
                    "title": "Not All Participants Remove Succeeded",
                    "error_data": {
                        "details": "ERROR_DETAILS"
                    }
                }
            ]
        }
    ]
}

Error al eliminar participantes

{
    "groups": [
        {
            "timestamp": "TIMESTAMP",
            "group_id": "GROUP_ID",
            "type": "group_participants_remove",
            "request_id": "REQUEST_ID",
            "failed_participants": [
                {
                    "input": "PHONE_NUMBER or WHATSAPP_ID"
                }
            ],
            "errors": [
                {
                    "code": "ERROR_CODE",
                    "message": "ERROR_MESSAGE",
                    "title": "ERROR_TITLE",
                    "error_data": {
                        "details": "ERROR_DETAILS"
                    }
                }
            ],
            "initiated_by": "business"
        }
    ]
}

Un participante abandona el grupo

Se envía cuando un participante abandona el grupo por su cuenta. initiated_by es "participant" y removed_participants contiene únicamente el wa_id del participante que salió.

Ejemplo

Ejemplo completo de Un participante abandona el grupo:

{
    "groups": [
        {
            "timestamp": "TIMESTAMP",
            "group_id": "GROUP_ID",
            "type": "group_participants_remove",
            "removed_participants": [
                {
                    "wa_id": "WHATSAPP_ID"
                }
            ],
            "initiated_by": "participant"
        }
    ]
}

Actualizar configuración del grupo

Se activa un evento group_settings_update cuando se actualiza el asunto, la descripción o la foto de perfil del grupo.

Ejemplo

Ejemplo completo de Actualizar configuración del grupo:

Actualización exitosa de la configuración

{
    "groups": [
        {
            "timestamp": "TIMESTAMP",
            "group_id": "GROUP_ID",
            "type": "group_settings_update",
            "request_id": "REQUEST_ID",
            "profile_picture": {
                "mime_type": "image/jpeg",
                "update_successful": true,
                "sha256": "PHOTO_HASH"
            },
            "group_subject": {
                "text": "Test Subject",
                "update_successful": true
            },
            "group_description": {
                "text": "Test Description",
                "update_successful": true
            }
        }
    ]
}

Error al actualizar la configuración

Cuando alguno de los campos falla, ese campo trae update_successful: false y su propio arreglo errors, además de un errors general en el evento:

{
    "groups": [
        {
            "timestamp": "TIMESTAMP",
            "group_id": "GROUP_ID",
            "type": "group_settings_update",
            "request_id": "REQUEST_ID",
            "profile_picture": {
                "mime_type": "image/jpeg",
                "update_successful": true,
                "sha256": "PHOTO_HASH"
            },
            "group_subject": {
                "text": "Test Subject",
                "update_successful": false,
                "errors": [
                    {
                        "code": "ERROR_CODE",
                        "message": "ERROR_MESSAGE",
                        "title": "ERROR_TITLE",
                        "error_data": {
                            "details": "ERROR_DETAILS"
                        }
                    }
                ]
            },
            "group_description": {
                "text": "Test Description",
                "update_successful": false,
                "errors": [
                    {
                        "code": "ERROR_CODE",
                        "message": "ERROR_MESSAGE",
                        "title": "ERROR_TITLE",
                        "error_data": {
                            "details": "ERROR_DETAILS"
                        }
                    }
                ]
            },
            "errors": [
                {
                    "code": "ERROR_CODE",
                    "message": "ERROR_MESSAGE",
                    "title": "ERROR_TITLE",
                    "error_data": {
                        "details": "ERROR_DETAILS"
                    }
                }
            ]
        }
    ]
}

Estado del grupo

Se activa un evento group_status_update cuando WhatsApp suspende un grupo que administrás, o cuando se retira la suspensión de un grupo previamente suspendido.

Ejemplo

Ejemplo completo de Estado del grupo:

Grupo suspendido

{
    "groups": [
        {
            "timestamp": "TIMESTAMP",
            "type": "group_suspend",
            "group_id": "GROUP_ID"
        }
    ]
}

Suspensión del grupo retirada

{
    "groups": [
        {
            "timestamp": "TIMESTAMP",
            "type": "group_suspend_cleared",
            "group_id": "GROUP_ID"
        }
    ]
}

Mensajes recibidos desde un grupo

Cuando un participante envía un mensaje a un grupo administrado por tu número, la notificación llega con la estructura general de mensajes, e incluye el campo group_id dentro del objeto del mensaje para identificar al grupo.

Ejemplo

{
    "contacts": [
        {
            "profile": { "name": "Héctor" },
            "wa_id": "5215500000001"
        }
    ],
    "messages": [
        {
            "from": "5215500000001",
            "group_id": "GROUP_ID",
            "id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA",
            "timestamp": "1617061836",
            "type": "text",
            "text": { "body": "Hola grupo" }
        }
    ]
}

Estatus de mensajes enviados a un grupo

Cuando se envían mensajes a un grupo se reciben webhooks de estatus (sent, delivered, read). En lugar de enviar un webhook por cada actualización, WhatsApp puede agregarlos: cada webhook siempre referencia un único grupo y un único estatus. Existen dos formas de agregación.

Estructura

Los estatus de mensajes enviados a un grupo (sent, delivered, read) llegan en el arreglo statuses, con la misma estructura de Notificaciones de Estatus, y estos campos adicionales:

Nombre	Descripción	Tipo
recipient_type	Siempre `group`.	String
recipient_participant_id	Número de teléfono del participante del grupo al que corresponde el estatus. No llega en el estatus `sent`. Se omite cuando el participante tiene un nombre de usuario y su número de teléfono no está disponible.	String (condicional)
recipient_participant_user_id	BSUID del participante del grupo. Siempre se incluye (excepto en el estatus `sent`).	String (condicional)
recipient_participant_parent_user_id	BSUID padre del participante del grupo. Solo se incluye si la empresa tiene portafolios vinculados.	String (opcional)
group_id	Identificador del grupo.	String (opcional)

Para las conversaciones de grupo, pricing.category y conversation.origin.type usan valores específicos de grupo: group_marketing, group_utility o group_service, y el pricing_model es PMP.

WhatsApp puede agregar varios estatus en un mismo webhook. Cada webhook siempre referencia un único grupo y un único estatus.

Nota: En los webhooks agregados, la plataforma reemplaza solo el id del primer estatus (statuses[0].id) con el id interno del mensaje; los id del resto de los estatus conservan el wamid original de Meta.

Ejemplo

Ejemplo completo de Estatus de mensajes enviados a un grupo:

Varios participantes, un mismo mensaje

Si se envía un mensaje y se reciben varios estatus delivered o read de distintos participantes, WhatsApp envía un único webhook agregado con múltiples objetos status: mismo grupo, mismo estatus y mismo mensaje, identificando a cada participante con recipient_participant_id.

{
    "statuses": [
        {
            "id": "WHATSAPP_MESSAGE_ID",
            "status": "read",
            "timestamp": "WEBHOOK_TRIGGER_TIMESTAMP",
            "recipient_id": "GROUP_ID",
            "recipient_type": "group",
            "recipient_participant_id": "GROUP_PARTICIPANT_PHONE_NUMBER_1",
            "conversation": {
                "id": "CONVERSATION_ID",
                "origin": {
                    "type": "CONVERSATION_CATEGORY"
                },
                "pricing": {
                    "billable": true,
                    "pricing_model": "PRICING_MODEL",
                    "category": "CONVERSATION_CATEGORY"
                }
            }
        },
        {
            "id": "WHATSAPP_MESSAGE_ID",
            "status": "read",
            "timestamp": "WEBHOOK_TRIGGER_TIMESTAMP",
            "recipient_id": "GROUP_ID",
            "recipient_type": "group",
            "recipient_participant_id": "GROUP_PARTICIPANT_PHONE_NUMBER_2",
            "conversation": {
                "id": "CONVERSATION_ID",
                "origin": {
                    "type": "CONVERSATION_CATEGORY"
                },
                "pricing": {
                    "billable": true,
                    "pricing_model": "PRICING_MODEL",
                    "category": "CONVERSATION_CATEGORY"
                }
            }
        }
    ]
}

Varios mensajes, un mismo participante

Si se envían varios mensajes a un grupo y se reciben varios estatus delivered o read de un mismo participante, WhatsApp puede enviar un único webhook agregado con múltiples objetos status: mismo grupo, mismo estatus y mismo participante, identificando cada mensaje con id.

{
    "statuses": [
        {
            "id": "WHATSAPP_MESSAGE_ID_1",
            "status": "delivered",
            "timestamp": "WEBHOOK_TRIGGER_TIMESTAMP",
            "recipient_id": "GROUP_ID",
            "recipient_type": "group",
            "recipient_participant_id": "GROUP_PARTICIPANT_PHONE_NUMBER",
            "conversation": {
                "id": "CONVERSATION_ID",
                "origin": {
                    "type": "CONVERSATION_CATEGORY"
                },
                "pricing": {
                    "billable": true,
                    "pricing_model": "PRICING_MODEL",
                    "category": "CONVERSATION_CATEGORY"
                }
            }
        },
        {
            "id": "WHATSAPP_MESSAGE_ID_2",
            "status": "delivered",
            "timestamp": "WEBHOOK_TRIGGER_TIMESTAMP",
            "recipient_id": "GROUP_ID",
            "recipient_type": "group",
            "recipient_participant_id": "GROUP_PARTICIPANT_PHONE_NUMBER",
            "conversation": {
                "id": "CONVERSATION_ID",
                "origin": {
                    "type": "CONVERSATION_CATEGORY"
                },
                "pricing": {
                    "billable": true,
                    "pricing_model": "PRICING_MODEL",
                    "category": "CONVERSATION_CATEGORY"
                }
            }
        }
    ]
}

Whatsapp — Anterior

Cambio de número del usuario

Siguiente — Whatsapp

Notificaciones de Flows