Веб-хуки для API групп | Документация для разработчиков
Веб-хуки для API групп
Обновлено: 11 февраля 2026 г
Для получения уведомлений через веб-перехватчики о метаданных ваших групп, пожалуйста, подпишитесь на следующие поля веб-перехватчика:
group_lifecycle_updategroup_participants_updategroup_settings_updategroup_status_updategroup_lifecycle_update вебхуки
Веб
group_lifecycle_update срабатывает при создании или удалении группы.Группа создает и добивается успеха
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "DISPLAY_PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"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"
}
]
},
"field": "group_lifecycle_update"
}
]
}
]
}
Создание группы не удалось
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "DISPLAY_PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID",
},
"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"
}
}
]
}
]
},
"field": "group_lifecycle_update"
}
]
}
]
}
Удаление группы прошло успешно
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "DISPLAY_PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID",
},
"groups": [
{
"timestamp": "TIMESTAMP",
"group_id": "GROUP_ID",
"type": "group_delete"
"request_id": "REQUEST_ID",
}
]
},
"field": "group_lifecycle_update"
}
]
}
]
}
Удаление группы не удаётся
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "DISPLAY_PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID",
},
"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"
}
}
]
}
]
},
"field": "group_lifecycle_update"
}
]
}
]
}
group_participants_update вебхуки
group_participants_update
, когда пользователь WhatsApp присоединяется к группе по ссылке-приглашению, отправляет запрос на вступление в группу, отменяет свой запрос или когда один или несколько запросов на вступление одобрены.Пользователь успешно присоединился к группе по ссылке-приглашению
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "DISPLAY_PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID",
},
"groups": [
{
"timestamp": "TIMESTAMP",
"group_id": "GROUP_ID",
"type": "group_participants_add",
"reason": "invite_link",
"added_participants": [
{
"wa_id": "WHATSAPP_ID",
},
]
}
]
},
"field": "group_participants_update"
}
]
}
]
}
Пользователь принимает или отменяет запрос на присоединение
параметр GROUP_REQUEST_TYPE устанавливается в значение group_join_request_created.Для отмены запросов: параметр GROUP_REQUEST_TYPE устанавливается в значение group_join_request_revoked.{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "BUSINESS_DISPLAY_PHONE_NUMBER",
"phone_number_id": "BUSINESS_PHONE_NUMBER_ID"
},
"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"
}
]
},
"field": "group_participants_update"
}
]
}
]
}
Запрос на присоединение одобрен
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "BUSINESS_DISPLAY_PHONE_NUMBER",
"phone_number_id": "BUSINESS_PHONE_NUMBER_ID"
},
"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"
},
// Дополнительные участники добавляются здесь, если одобрены массово .
]
}
]
},
"field": "group_participants_update"
}
]
}
]
}
Участник группы успешно удаляет
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "DISPLAY_PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID",
},
"groups": [
{
"timestamp": "TIMESTAMP",
"group_id": "GROUP_ID",
"type": "group_participants_remove",
"request_id": "REQUEST_ID",
"removed_participants": [
// Пользователь 1 успешно удален
{
"input": "PHONE_NUMBER or WHATSAPP_ID"
},
{
"input": "PHONE_NUMBER or WHATSAPP_ID"
},
...
]
}
"initiated_by": "business"
]
},
"field": "group_participants_update"
}
]
}
]
}
Удаление участника группы при частичном сбое участников
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "DISPLAY_PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID",
},
"groups": [
{
"timestamp": "TIMESTAMP",
"group_id": "GROUP_ID",
"type": "group_participants_remove",
"request_id": "REQUEST_ID",
"initiated_by": business,
"removed_participants": [
// Пользователь 1 успешно удален
{
"input": "НОМЕР_ТЕЛЕФОНА или ИД_WHATSAPP"
},
// Дополнительные пользователи успешно
...
],
"failed_participants": [
// Пользователь 2 не удален из-за ошибок
{
"input": "НОМЕР_ТЕЛЕФОНА или ИД_WHATSAPP"
"errors": [
{
"code": "КОД_ОШИБКИ",
"message": "СООБЩЕНИЕ_ОШИБКИ",
"title": "ЗАГОЛОВОК_ОШИБКИ",
"error_data": {
"details": "ПОДРОБНОСТИ_ОШИБКИ"
}
}
]
}
],
"errors": [
{
"code": "КОД_ОШИБКИ",
"message": "Не удалось удалить некоторых участников из группы",
"title": "Удаление не всех участников удалось",
"error_data": {
"details": "ERROR_DETAILS"
}
}
]
}
"initiated_by": "business"
]
},
"field": "group_participants_update"
}
]
}
]
}
Удаление участника группы не удается
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "DISPLAY_PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID",
},
"groups": [
{
"timestamp": "TIMESTAMP",
"group_id": "GROUP_ID",
"type": "group_participants_remove",
"request_id": "REQUEST_ID",
"failed_participants": [
{
"input": "PHONE_NUMBER or WHATSAPP_ID"
},
{
"input": "PHONE_NUMBER or WHATSAPP_ID"
},
дополнительных пользователейудалить
...
],
"errors": [
{
"code": "ERROR_CODE",
"message": "ERROR_MESSAGE",
"title": "ERROR_TITLE",
"error_data": {
"details": "ERROR_DETAILS"
}
}
]
}
"initiated_by": "business"
]
},
"field": "group_participants_update"
}
]
}
]
}
Участник группы покидает веб-хук
Этот веб-хук отправляется, когда участник группы покидает группу.
initiated_by и только wa_id в removed_participants будут указывать на участника, покинувшего группу.{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "DISPLAY_PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID",
},
"groups": [
{
"timestamp": "TIMESTAMP",
"group_id": "GROUP_ID",
"type": "group_participants_remove",
"removed_participants": [
{
"wa_id": "WHATSAPP_ID",
}
]
}
"initiated_by": "participant"
]
},
"field": "group_participants_update"
}
]
}
]
}
group_settings_update веб-хуки
Обновление настроек группы прошло успешно
{
"object": "whatsapp_business_account",
"entry": [
{
"id": ",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "DISPLAY_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"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,
}
}
]
},
"field": "group_settings_update"
}
]
}
]
}
Обновление настроек группы частично завершилось с ошибкой
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "DISPLAY_PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"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"
}
}
]
}
]
},
"field": "group_settings_update"
}
]
}
]
}
Обновление настроек группы завершилось неудачей
{
"object": "whatsapp_business_account",
"entry": [
{
"id": ",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "DISPLAY_PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER"
},
"groups": [
{
"timestamp": "TIMESTAMP",
"group_id": "GROUP_ID",
"request_id": "REQUEST_ID",
"type": "group_settings_update",
"profile_picture": {
"mime_type": "image/jpeg",
"sha256": "PHOTO_HASH",
"update_successful": false,
"errors": [
{
"code": "ERROR_CODE",
"message": "ERROR_MESSAGE",
"title": "ERROR_TITLE",
"error_data": {
"details": "ERROR_DETAILS"
}
}
]
},
"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"
}
}
]
}
]
},
"field": "group_settings_update"
}
]
}
]
}
group_status_update вебхуки
WhatsApp использует передовые технологии машинного обучения для анализа информации о группах, включая темы обсуждений, фотографии профилей и описания групп. Мы также предоставляем пользователям простые возможности для отправки нам отчетов из любого чата.
если администратор группы нарушает наши Условия предоставления услуг.,
Вы можете получить веб-хук, если группа, которой вы управляете, будет заблокирована. Вы также можете получить веб-хук, если заблокированная группа, которой вы управляете, перестанет быть заблокированной.
Группа отстранена
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "DISPLAY_PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"groups": [
{
"timestamp": "TIMESTAMP",
"type": "group_suspend",
"group_id": "GROUP_ID"
}
]
},
"field": "group_status_update"
}
]
}
]
}
Отстранение от группы снято
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "DISPLAY_PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"groups": [
{
"timestamp": "TIMESTAMP",
"type": "group_suspend_cleared",
"group_id": "GROUP_ID"
}
]
},
"field": "group_status_update"
}
]
}
]
}
Веб-перехватчики статуса групповых сообщений
При отправке сообщений группе вы будете получать веб-перехватчик статуса, когда сообщение будет отправлено, доставлено и прочитано. Вместо отправки нескольких веб-перехватчиков для каждого обновления статуса мы можем отправлять агрегированный веб-перехватчик.
Вы можете получать два типа агрегированных веб-хуков состояния сообщений.
Несколько участников, одно сообщение
Если вы отправляете сообщение и настроены на получение нескольких
«прочитано» или «доставлено» от участников, мы отправим вам один агрегированный веб-хук, содержащий несколько статуса объектовКаждый полученный вами веб-хук будет относиться к одному сообщению, отправленному одной группе и одному типу статуса, то есть одной группе, одному статусу от нескольких участников для одного сообщения.
Сводная информация о статусе групповых сообщений
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "BUSINESS_DISPLAY_PHONE_NUMBER",
"phone_number_id": "BUSINESS_PHONE_NUMBER_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": IS_BILLABLE,
"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": IS_BILLABLE,
"pricing_model": "PRICING_MODEL",
"category": "CONVERSATION_CATEGORY"
}
}
}
]
},
"field": "messages"
}
]
}
]
}
Несколько сообщений, один участник
Если вы отправляете несколько сообщений группе и настроены на получение нескольких статусов «прочитано» или
«доставлено» от одного участника, мы можем отправить вам один агрегированный веб-хук, содержащий несколько статуса .Каждый полученный вами веб-хук будет относиться к нескольким сообщениям, отправленным одной группе и одному типу статуса, то есть одной группе, одному статусу от одного участника для нескольких сообщений.
Сводная информация о статусе групповых сообщений
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "BUSINESS_DISPLAY_PHONE_NUMBER",
"phone_number_id": "BUSINESS_PHONE_NUMBER_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": IS_BILLABLE,
"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": IS_BILLABLE,
"pricing_model": "PRICING_MODEL",
"category": "CONVERSATION_CATEGORY"
}
}
}
]
},
"field": "messages"
}
]
}
]
}
Групповое сообщение доставлено
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "BUSINESS_DISPLAY_PHONE_NUMBER",
"phone_number_id": "BUSINESS_PHONE_NUMBER_ID"
},
"statuses": [
{
"id": "WHATSAPP_MESSAGE_ID",
"status": "delivered",
"timestamp": "WEBHOOK_TRIGGER_TIMESTAMP",
"recipient_id": "GROUP_ID",
"recipient_type": "group",
"participant_recipient_id": "GROUP_PARTICIPANT_PHONE_NUMBER",
"conversation": {
"id": "CONVERSATION_ID",
"origin": {
"type": "CONVERSATION_CATEGORY"
}
},
"pricing": {
"billable": IS_BILLABLE,
"pricing_model": "PRICING_MODEL",
"category": "CONVERSATION_CATEGORY"
}
}
]
},
"field": "messages"
}
]
}
]
}
Информация о ценах
Сообщения о состоянии, содержащие вебхуки с информацией о ценах, будут иметь следующую информацию:
Параметр CONVERSATION_CATEGORY установлен в одно из следующих значений:
group_marketing — Обозначает маркетинговую дискуссию.group_utility — Указывает на разговор, связанный с утилитой.group_service — Указывает на диалог между службами.Значение IS_BILLABLE установлено в одно из следующих значений:
true — Указывает на платный разговор.false — Указывает на разговор, не подлежащий оплате.PRICING_MODEL установлен на PMP.Групповое сообщение прочитано (с указанием цен)
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "BUSINESS_DISPLAY_PHONE_NUMBER",
"phone_number_id": "BUSINESS_PHONE_NUMBER_ID"
},
"statuses": [
{
"id": "WHATSAPP_MESSAGE_ID",
"status": "read",
"timestamp": "WEBHOOK_TRIGGER_TIMESTAMP",
"recipient_id": "GROUP_ID",
"recipient_type": "group",
"participant_recipient_id": "GROUP_PARTICIPANT_PHONE_NUMBER",
"conversation": {
"id": "CONVERSATION_ID",
"origin": {
"type": "CONVERSATION_CATEGORY"
}
},
"pricing": {
"billable": IS_BILLABLE,
"pricing_model": "PRICING_MODEL",
"category": "CONVERSATION_CATEGORY"
}
}
]
},
"field": "messages"
}
]
}
]
}
Групповое сообщение прочитано (без указания цены)
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "BUSINESS_DISPLAY_PHONE_NUMBER",
"phone_number_id": "BUSINESS_PHONE_NUMBER_ID"
},
"statuses": [
{
"id": "WHATSAPP_MESSAGE_ID",
"status": "read",
"timestamp": "WEBHOOK_TRIGGER_TIMESTAMP",
"recipient_id": "GROUP_ID",
"recipient_type": "group"
"participant_recipient_id": "GROUP_PARTICIPANT_PHONE_NUMBER"
}
]
},
"field": "messages"
}
]
}
]
}