> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# whatsapp.group.status_update

> Происходит при обновлении статуса блокировки группы WhatsApp.

Используйте `whatsapp.group.status_update` для обработки этого события на вашей конечной точке Webhook.

## Триггеры

Происходит при обновлении статуса блокировки группы WhatsApp.

Подпишитесь на `whatsapp.group.status_update`, когда будете [настраивать свою конечную точку Webhook](https://docs.ycloud.com/ru/api-reference/guides/api-fundamentals/configure-webhooks.md).

## Синтаксис

YCloud отправляет HTTP-запрос `POST` на настроенный вами URL Webhook. Ниже представлена одна из структур полезной нагрузки. Значения в угловых скобках являются заполнителями; их типы перечислены в разделе **Параметры**. Необязательные поля и другие варианты описаны ниже.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "<ID>",
  "type": "whatsapp.group.status_update",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappGroup": {
    "wabaId": "<WABA_ID>",
    "field": "<FIELD>",
    "type": "<TYPE>",
    "status": "<STATUS>",
    "groupId": "<GROUP_ID>",
    "webhookTime": "<WEBHOOK_TIME>"
  }
}
```

## Параметры

Проверяйте HTTP-заголовок `YCloud-Signature` перед обработкой тела JSON. См. раздел [проверка подписи](https://docs.ycloud.com/ru/api-reference/guides/api-fundamentals/configure-webhooks.md).

### Конверт события

| Параметр | Тип | Обязательный | Описание |
| - | - | - | - |
| `id` | string | Да | Уникальный идентификатор события. Минимальная длина: `6`. Максимальная длина: `128`. |
| `type` | string | Да | Всегда `whatsapp.group.status_update`. |
| `apiVersion` | string | Да | Версия API, используемая для формирования этого события. |
| `createTime` | string (date-time) | Да | Время создания этого события, отформатированное в [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). Например, `2022-06-01T12:00:00.000Z`. |

### Полезная нагрузка события

| Параметр | Тип | Обязательный | Описание |
| - | - | - | - |
| `whatsappGroup` | object | Нет | Полезная нагрузка `whatsappGroup`, специфичная для события. |

Четыре общих поля конверта являются обязательными. Поля полезной нагрузки зависят от варианта события. В таблице каждого объекта признак **Обязательный** применяется тогда, когда присутствует его родительский объект. Необязательные поля могут быть опущены; наличие поля в примере не делает его обязательным.

#### whatsappGroup

| Параметр | Тип | Обязательный | Описание |
| - | - | - | - |
| `wabaId` | string | Нет | Идентификатор WhatsApp Business Account. |
| `displayPhoneNumber` | string | Нет | Отображаемый номер телефона из метаданных Webhook WhatsApp. |
| `phoneNumberId` | string | Нет | Идентификатор номера телефона WhatsApp. |
| `field` | string | Нет | Поле Webhook WhatsApp, создавшее событие группы.Значения: `group_lifecycle_update`, `group_participants_update`, `group_settings_update`, `group_status_update`, `messages`. |
| `type` | string | Нет | Конкретный тип события группы WhatsApp.Значения: `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`, `message_status`. |
| `requestId` | string | Нет | Идентификатор запроса, возвращенный асинхронной операцией API для групп. |
| `status` | string | Нет | Статус Webhook группы WhatsApp.Значения: `created`, `failed`, `deleted`, `added`, `removed`, `left`, `requested`, `revoked`, `updated`, `suspended`, `suspend_cleared`, `sent`, `delivered`, `read`, `expired`. |
| `groupId` | string | Нет | Идентификатор группы WhatsApp. |
| `messageId` | string | Нет | Идентификатор группового сообщения YCloud. Присутствует только тогда, когда событие статуса связано с сохраненным исходящим групповым сообщением. |
| `inviteLink` | string | Нет | Ссылка-приглашение в группу. |
| `reason` | string | Нет | Причина события, связанного с участником, запросом на вступление или удалением. |
| `initiatedBy` | string | Нет | Указывает, кто инициировал событие удаления участника.Значения: `business`, `participant`. |
| `joinRequestId` | string | Нет | Идентификатор запроса на вступление. |
| `waId` | string | Нет | Идентификатор пользователя WhatsApp для отдельного события участника. |
| `recipientUserId` | string | Нет | Идентификатор пользователя в рамках бизнеса (Business-scoped user ID) для отдельного события участника. |
| `parentRecipientUserId` | string | Нет | Идентификатор пользователя в рамках родительского бизнеса (Parent business-scoped user ID) для отдельного события участника. |
| `customerProfile` | object | Нет | Данные профиля клиента WhatsApp. |
| `subject` | string | Нет | Тема группы. |
| `description` | string | Нет | Описание группы. |
| `joinApprovalMode` | string | Нет | Режим одобрения вступления в группу WhatsApp.<ul><li>`approval_required`: новые участники должны быть одобрены перед вступлением.</li><li>`auto_approve`: новые участники могут вступать без одобрения.</li></ul> |
| `addedParticipants` | object\[] | Нет | Участники, добавленные в группу. |
| `removedParticipants` | object\[] | Нет | Участники, удаленные из группы. |
| `failedParticipants` | object\[] | Нет | Участники, которых не удалось добавить или удалить. |
| `settings` | object\[] | Нет | Сведения об изменении настроек группы. |
| `errors` | object\[] | Нет | Ошибки, возвращенные WhatsApp. |
| `contacts` | object\[] | Нет | Контакты, включенные в вебхуки со статусом групповых сообщений. |
| `statuses` | object\[] | Нет | Сведения о статусе группового сообщения. |
| `webhookTime` | string (date-time) | Нет | Время, когда WhatsApp вызвал этот Webhook. |
| `dedupeKey` | string | Нет | Ключ идемпотентности для дедупликации событий группового Webhook. |

> [accordion] whatsappGroup.customerProfile
>
> | Параметр | Тип | Обязательный | Описание |
> | - | - | - | - |
> | `name` | string | Нет | Имя профиля WhatsApp. |
> | `username` | string | Нет | Имя пользователя WhatsApp. |

> [accordion] whatsappGroup.addedParticipants\[]
>
> | Параметр | Тип | Обязательный | Описание |
> | - | - | - | - |
> | `input` | string | Нет | Исходные введенные данные участника. |
> | `waId` | string | Нет | Идентификатор пользователя WhatsApp. |
> | `recipientUserId` | string | Нет | Идентификатор пользователя в рамках бизнеса (Business-scoped user ID). |
> | `parentRecipientUserId` | string | Нет | Идентификатор пользователя в рамках родительского бизнеса (Parent business-scoped user ID). |
> | `customerProfile` | object | Нет | Данные профиля клиента WhatsApp. |
> | `errors` | object\[] | Нет | Ошибки, возвращенные WhatsApp для этого участника. |

> [accordion] whatsappGroup.addedParticipants\[].customerProfile
>
> | Параметр | Тип | Обязательный | Описание |
> | - | - | - | - |
> | `name` | string | Нет | Имя профиля WhatsApp. |
> | `username` | string | Нет | Имя пользователя WhatsApp. |

> [accordion] whatsappGroup.removedParticipants\[]
>
> | Параметр | Тип | Обязательный | Описание |
> | - | - | - | - |
> | `input` | string | Нет | Исходные переданные данные участника. |
> | `waId` | string | Нет | Идентификатор пользователя WhatsApp. |
> | `recipientUserId` | string | Нет | Идентификатор пользователя в рамках компании (Business-scoped user ID). |
> | `parentRecipientUserId` | string | Нет | Родительский идентификатор пользователя в рамках компании (Parent business-scoped user ID). |
> | `customerProfile` | object | Нет | Данные профиля клиента в WhatsApp. |
> | `errors` | object\[] | Нет | Ошибки, возвращенные WhatsApp для этого участника. |

> [accordion] whatsappGroup.removedParticipants\[].customerProfile
>
> | Параметр | Тип | Обязательный | Описание |
> | - | - | - | - |
> | `name` | string | Нет | Имя профиля в WhatsApp. |
> | `username` | string | Нет | Имя пользователя WhatsApp. |

> [accordion] whatsappGroup.failedParticipants\[]
>
> | Параметр | Тип | Обязательный | Описание |
> | - | - | - | - |
> | `input` | string | Нет | Исходные переданные данные участника. |
> | `waId` | string | Нет | Идентификатор пользователя WhatsApp. |
> | `recipientUserId` | string | Нет | Идентификатор пользователя в рамках компании (Business-scoped user ID). |
> | `parentRecipientUserId` | string | Нет | Родительский идентификатор пользователя в рамках компании (Parent business-scoped user ID). |
> | `customerProfile` | object | Нет | Данные профиля клиента в WhatsApp. |
> | `errors` | object\[] | Нет | Ошибки, возвращенные WhatsApp для этого участника. |

> [accordion] whatsappGroup.failedParticipants\[].customerProfile
>
> | Параметр | Тип | Обязательный | Описание |
> | - | - | - | - |
> | `name` | string | Нет | Имя профиля в WhatsApp. |
> | `username` | string | Нет | Имя пользователя WhatsApp. |

> [accordion] whatsappGroup.settings\[]
>
> | Параметр | Тип | Обязательный | Описание |
> | - | - | - | - |
> | `name` | string | Нет | Имя настройки.Значения: `profile_picture`, `group_subject`, `group_description`. |
> | `text` | string | Нет | Текстовое значение для обновления темы или описания. |
> | `updateSuccessful` | boolean | Нет | Указывает, успешно ли обновлена настройка. |
> | `mimeType` | string | Нет | MIME-тип для обновлений фото профиля. |
> | `sha256` | string | Нет | Хеш SHA-256 для обновлений фото профиля. |
> | `errors` | object\[] | Нет | Ошибки, возвращенные WhatsApp для этой настройки. |

> [accordion] whatsappGroup.contacts\[]
>
> | Параметр | Тип | Обязательный | Описание |
> | - | - | - | - |
> | `customerProfile` | object | Нет | Данные профиля клиента в WhatsApp. |
> | `waId` | string | Нет | Идентификатор пользователя WhatsApp. |
> | `recipientUserId` | string | Нет | Идентификатор пользователя в рамках компании (Business-scoped user ID). |
> | `parentRecipientUserId` | string | Нет | Родительский идентификатор пользователя в рамках компании (Parent business-scoped user ID). |

> [accordion] whatsappGroup.contacts\[].customerProfile
>
> | Параметр | Тип | Обязательный | Описание |
> | - | - | - | - |
> | `name` | string | Нет | Имя профиля в WhatsApp. |
> | `username` | string | Нет | Имя пользователя WhatsApp. |

> [accordion] whatsappGroup.statuses\[]
>
> | Параметр | Тип | Обязательный | Описание |
> | - | - | - | - |
> | `id` | string | Нет | Идентификатор сообщения WhatsApp. |
> | `status` | string | Нет | Статус сообщения.Значения: `sent`, `delivered`, `read`, `failed`, `expired`. |
> | `timestamp` | integer (int64) | Нет | Временная метка Unix, указывающая, когда был обновлен статус сообщения. |
> | `recipientId` | string | Нет | Идентификатор группы получателя. |
> | `recipientType` | string | Нет | Тип получателя.Значения: `group`. |
> | `recipientParticipantId` | string | Нет | Идентификатор пользователя WhatsApp участника-получателя. |
> | `recipientUserId` | string | Нет | Идентификатор пользователя в рамках бизнеса (business-scoped user ID) участника-получателя. |
> | `parentRecipientUserId` | string | Нет | Родительский идентификатор пользователя в рамках бизнеса (parent business-scoped user ID) участника-получателя. |
> | `conversation` | object | Нет | Объект переписки WhatsApp, включенный в webhook-уведомления о статусе группового сообщения. |
> | `pricing` | object | Нет | Информация о тарификации, включенная в webhook-уведомления о статусе группового сообщения. |
> | `errors` | object\[] | Нет | Ошибки, возвращенные WhatsApp. |

> [accordion] whatsappGroup.statuses\[].conversation
>
> | Параметр | Тип | Обязательный | Описание |
> | - | - | - | - |
> | `id` | string | Нет | Идентификатор переписки. |
> | `expirationTimestamp` | integer (int64) | Нет | Временная метка Unix, указывающая время истечения срока действия переписки. |
> | `origin` | object | Нет | Поля объекта перечислены ниже. |

> [accordion] whatsappGroup.statuses\[].conversation.origin
>
> | Параметр | Тип | Обязательный | Описание |
> | - | - | - | - |
> | `type` | string | Нет | Тип источника переписки. |

> [accordion] whatsappGroup.statuses\[].pricing
>
> | Параметр | Тип | Обязательный | Описание |
> | - | - | - | - |
> | `billable` | boolean | Нет | Подлежит ли сообщение оплате. |
> | `pricingModel` | string | Нет | Модель ценообразования. |
> | `type` | string | Нет | Тип тарификации. |
> | `category` | string | Нет | Необработанная категория тарификации группы, переданная Meta. YCloud не раскрывает внутреннее сопоставление MM Lite в этом поле webhook.Значения: `group_marketing`, `group_utility`, `group_service`. |

## Пример

Следующий JSON представляет собой тело запроса, доставленное вашему получателю. Идентификаторы, номера телефонов и другие значения аккаунта приведены в качестве примера.

> [accordion] Событие обновления статуса группы WhatsApp
>
> Пример полезной нагрузки при изменении статуса блокировки группы WhatsApp
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "id": "evt_group_status_123",
>   "type": "whatsapp.group.status_update",
>   "apiVersion": "v2",
>   "createTime": "2026-05-13T00:00:00.000Z",
>   "whatsappGroup": {
>     "wabaId": "123456789012345",
>     "field": "group_status_update",
>     "type": "group_suspend",
>     "status": "suspended",
>     "groupId": "120363345678901234@g.us",
>     "webhookTime": "2026-05-13T00:00:00.000Z"
>   }
> }
> ```

> [accordion] Группа заблокирована
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "id": "evt_group_status_123",
>   "type": "whatsapp.group.status_update",
>   "apiVersion": "v2",
>   "createTime": "2026-05-13T00:00:00.000Z",
>   "whatsappGroup": {
>     "wabaId": "123456789012345",
>     "field": "group_status_update",
>     "type": "group_suspend",
>     "status": "suspended",
>     "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
>     "webhookTime": "2026-05-13T00:00:00.000Z"
>   }
> }
> ```

> [accordion] Блокировка группы снята
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "id": "evt_group_status_124",
>   "type": "whatsapp.group.status_update",
>   "apiVersion": "v2",
>   "createTime": "2026-05-13T00:00:00.000Z",
>   "whatsappGroup": {
>     "wabaId": "123456789012345",
>     "field": "group_status_update",
>     "type": "group_suspend_cleared",
>     "status": "suspend_cleared",
>     "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
>     "webhookTime": "2026-05-13T00:00:00.000Z"
>   }
> }
> ```

После проверки подписи и надежного сохранения события верните ответ `2xx`. Длительные операции выполняйте асинхронно.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

Разбор сценариев см. в разделе [примеров с пояснениями](https://docs.ycloud.com/ru/api-reference/guides/examples/webhook-examples/whatsapp-group-status-update-webhook-examples).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.