Group notifications

Last update: 5 hours ago by Irais Aguirre

Integration summary
Delivery: WhatsApp → Concepto Móvil → POST to your webhook URL (the one you share with our Operations team), with a JSON body.
Format: Meta's value object without metadata or messaging_product (see Webhook).
Identify the user: from/recipient_id or, if missing, the BSUID.
Types on this page: 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 (type values) and status of messages sent to a group

Events for your number's groups: group creation and deletion, participant changes, join requests, group settings, and group suspension. To create and manage groups, see Groups.

General structure

Structure shared by every group event.

Structure

Fields for General structure:

Name	Description	Type
groups	List of group events. Each object includes at least `timestamp`, `group_id`, and `type`; the other fields depend on the event type (see Examples).	Object list

Values of the type field:

Value	Event
group_create	Result of creating a group.
group_delete	Result of deleting a group.
group_participants_add	A user joined the group (for example, through the invite link).
group_participants_remove	One or more participants were removed, or a participant left the group (`initiated_by` indicates who triggered it).
group_join_request_created	A user requested to join a group that requires approval.
group_join_request_revoked	A user canceled their join request.
group_settings_update	Result of updating the group's subject, description, or profile picture.
group_suspend	WhatsApp suspended the group.
group_suspend_cleared	The group's suspension was lifted.

Note: participant objects (added_participants, removed_participants, failed_participants) and join-request events identify the user with the same rules as message notifications: user_id (BSUID) is always included, wa_id is included only when the phone number is available, parent_user_id is included only if the business has linked portfolios, and username is included only if the user has one. See Usernames and BSUID. For brevity, some examples below show only wa_id or input.

Create a group

The type field is "group_create".

Example

Complete Create a group example:

Group created successfully

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

Group creation failed

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

Delete a group

The type field is "group_delete".

Example

Complete Delete a group example:

{
    "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 is included only if the deletion failed.

A user joins the group through an invite link

The type field is "group_participants_add".

Example

Complete A user joins the group through an invite link example:

{
    "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 is always included; wa_id, parent_user_id and username are included only in the cases described in the note above.

A user creates or cancels a join request

Applies to groups whose join_approval_mode requires approval. The type field indicates the event:

Request created: type is group_join_request_created.
Request canceled: type is group_join_request_revoked.

Example

Complete A user creates or cancels a join request example:

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

Join request approved

When the request is approved (manually or automatically), a group_participants_add event with reason: "invite_link" is also sent:

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

Remove participants from a group

A group_participants_remove event is triggered when the business removes one or more participants from the group (initiated_by: "business").

Example

Complete Remove participants from a group example:

Participants removed successfully

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

Participants partially removed

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

Participant removal failed

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

A participant leaves the group

Sent when a participant leaves the group on their own. initiated_by is "participant" and removed_participants contains only the wa_id of the participant who left.

Example

Complete A participant leaves the group example:

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

Update group settings

A group_settings_update event is triggered when the group subject, description, or profile picture is updated.

Example

Complete Update group settings example:

Settings updated successfully

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

Settings update failed

When a field fails to update, that field includes update_successful: false and its own errors array, in addition to a general errors array on the event:

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

Group status

A group_status_update event is triggered when WhatsApp suspends a group you manage, or when the suspension is lifted from a previously suspended group.

Example

Complete Group status example:

Group suspended

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

Group suspension lifted

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

Messages received from a group

When a participant sends a message to a group managed by your number, the notification arrives with the general message structure, including the group_id field inside the message object to identify the group.

Example

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

Status of messages sent to a group

When you send messages to a group, you receive status webhooks (sent, delivered, read). Instead of sending one webhook per update, WhatsApp can aggregate them; each webhook always refers to a single group and a single status. There are two kinds of aggregation.

Structure

Statuses for messages sent to a group (sent, delivered, read) arrive in the statuses array, with the same structure as Status notifications plus these additional fields:

Name	Description	Type
recipient_type	Always `group`.	String
recipient_participant_id	Phone number of the group participant the status applies to. Not present in the `sent` status. Omitted when the participant has a username and their phone number is unavailable.	String (conditional)
recipient_participant_user_id	BSUID of the group participant. Always included (except in the `sent` status).	String (conditional)
recipient_participant_parent_user_id	Parent BSUID of the group participant. Only included if the business has linked portfolios.	String (optional)
group_id	Group identifier.	String (optional)

For group conversations, the pricing.category and conversation.origin.type use group-specific values: group_marketing, group_utility or group_service, and the pricing_model is PMP.

WhatsApp may aggregate several statuses into a single webhook. Each webhook always refers to a single group and a single status.

Note: In aggregated webhooks, the platform only replaces the id of the first status (statuses[0].id) with the internal message id; the id of the remaining statuses keeps Meta's original wamid.

Example

Complete Status of messages sent to a group example:

Multiple participants, same message

If you send a message and several participants report a delivered or read status, WhatsApp sends a single aggregated webhook with multiple status objects: same group, same status, and same message, with each participant identified by 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"
                }
            }
        }
    ]
}

Multiple messages, same participant

If you send several messages to a group and the same participant reports a delivered or read status for them, WhatsApp may send a single aggregated webhook with multiple status objects: same group, same status, and same participant, with each message identified by 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 — Previous

User changed phone number

Next — WhatsApp

Flows notifications