whatsapp.group.participants_update

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

Триггеры

Происходит при обновлении списка участников группы WhatsApp или запросов на вступление. Подпишитесь на whatsapp.group.participants_update, когда будете настраивать конечную точку Webhook.

Синтаксис

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

{
  "id": "<ID>",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappGroup": {
    "wabaId": "<WABA_ID>",
    "field": "<FIELD>",
    "type": "<TYPE>",
    "status": "<STATUS>",
    "groupId": "<GROUP_ID>",
    "waId": "<WA_ID>",
    "recipientUserId": "<RECIPIENT_USER_ID>",
    "parentRecipientUserId": "<PARENT_RECIPIENT_USER_ID>",
    "customerProfile": {
      "name": "<NAME>",
      "username": "<USERNAME>"
    },
    "addedParticipants": [
      {
        "input": "<INPUT>",
        "waId": "<WA_ID>",
        "recipientUserId": "<RECIPIENT_USER_ID>",
        "parentRecipientUserId": "<PARENT_RECIPIENT_USER_ID>",
        "customerProfile": {
          "name": "<NAME>",
          "username": "<USERNAME>"
        }
      }
    ],
    "webhookTime": "<WEBHOOK_TIME>"
  }
}

Параметры

Проверьте HTTP-заголовок YCloud-Signature, прежде чем обрабатывать тело JSON. См. раздел проверка подписи.

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

Параметр	Тип	Обязательный	Описание
`id`	string	Да	Уникальный идентификатор события. Минимальная длина: `6`. Максимальная длина: `128`.
`type`	string	Да	Всегда `whatsapp.group.participants_update`.
`apiVersion`	string	Да	Версия API, используемая для формирования этого события.
`createTime`	string (date-time)	Да	Время создания этого события в формате RFC 3339. Например, `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) для события с одним участником.
`parentRecipientUserId`	string	Нет	Родительский идентификатор пользователя в рамках компании (business-scoped) для события с одним участником.
`customerProfile`	object	Нет	Информация профиля клиента WhatsApp.
`subject`	string	Нет	Тема группы.
`description`	string	Нет	Описание группы.
`joinApprovalMode`	string	Нет	Режим одобрения вступления в группу WhatsApp. `approval_required`: новые участники должны быть одобрены перед вступлением. `auto_approve`: новые участники могут вступать без одобрения.
`addedParticipants`	object[]	Нет	Участники, добавленные в группу.
`removedParticipants`	object[]	Нет	Участники, удаленные из группы.
`failedParticipants`	object[]	Нет	Участники, которых не удалось добавить или удалить.
`settings`	object[]	Нет	Сведения об обновлении настроек группы.
`errors`	object[]	Нет	Ошибки, возвращенные WhatsApp.
`contacts`	object[]	Нет	Контакты, включенные в вебхуки со статусом групповых сообщений.
`statuses`	object[]	Нет	Сведения о статусе группового сообщения.
`webhookTime`	string (date-time)	Нет	Время, когда WhatsApp вызвал этот Webhook.
`dedupeKey`	string	Нет	Ключ идемпотентности для дедупликации событий группового Webhook.

whatsappGroup.customerProfile

Параметр	Тип	Обязательный	Описание
`name`	string	Нет	Имя профиля WhatsApp.
`username`	string	Нет	Имя пользователя WhatsApp.

whatsappGroup.addedParticipants[]

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

whatsappGroup.addedParticipants[].customerProfile

Параметр	Тип	Обязательный	Описание
`name`	string	Нет	Имя профиля WhatsApp.
`username`	string	Нет	Имя пользователя WhatsApp.

whatsappGroup.removedParticipants[]

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

whatsappGroup.removedParticipants[].customerProfile

Параметр	Тип	Обязательный	Описание
`name`	string	Нет	Имя профиля WhatsApp.
`username`	string	Нет	Имя пользователя WhatsApp.

whatsappGroup.failedParticipants[]

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

whatsappGroup.failedParticipants[].customerProfile

Параметр	Тип	Обязательный	Описание
`name`	string	Нет	Имя профиля WhatsApp.
`username`	string	Нет	Имя пользователя WhatsApp.

whatsappGroup.settings[]

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

whatsappGroup.contacts[]

Параметр	Тип	Обязательный	Описание
`customerProfile`	object	Нет	Информация о профиле клиента в WhatsApp.
`waId`	string	Нет	Идентификатор пользователя WhatsApp.
`recipientUserId`	string	Нет	Идентификатор пользователя в рамках компании (business-scoped user ID).
`parentRecipientUserId`	string	Нет	Родительский идентификатор пользователя в рамках компании (business-scoped user ID).

whatsappGroup.contacts[].customerProfile

Параметр	Тип	Обязательный	Описание
`name`	string	Нет	Имя профиля WhatsApp.
`username`	string	Нет	Имя пользователя WhatsApp.

whatsappGroup.statuses[]

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

whatsappGroup.statuses[].conversation

Параметр	Тип	Обязательный	Описание
`id`	string	Нет	Идентификатор переписки.
`expirationTimestamp`	integer (int64)	Нет	Unix timestamp, указывающий, когда истекает срок действия переписки.
`origin`	object	Нет	Поля объекта перечислены ниже.

whatsappGroup.statuses[].conversation.origin

Параметр	Тип	Обязательный	Описание
`type`	string	Нет	Тип источника переписки.

whatsappGroup.statuses[].pricing

Параметр	Тип	Обязательный	Описание
`billable`	boolean	Нет	Указывает, подлежит ли сообщение оплате.
`pricingModel`	string	Нет	Модель ценообразования.
`type`	string	Нет	Тип тарификации.
`category`	string	Нет	Исходная категория тарификации группы, предоставленная Meta. YCloud не раскрывает внутреннее сопоставление MM Lite в этом поле Webhook. Значения: `group_marketing`, `group_utility`, `group_service`.

Пример

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

Событие обновления участников группы WhatsApp

Пример полезной нагрузки при добавлении участников группы WhatsApp

{
  "id": "evt_group_participants_123",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_participants_update",
    "type": "group_participants_add",
    "status": "added",
    "groupId": "120363345678901234@g.us",
    "waId": "16315551111",
    "recipientUserId": "US.1234",
    "parentRecipientUserId": "US.parent123",
    "customerProfile": {
      "name": "John Doe",
      "username": "john_doe"
    },
    "addedParticipants": [
      {
        "input": "US.1234",
        "waId": "16315551111",
        "recipientUserId": "US.1234",
        "parentRecipientUserId": "US.parent123",
        "customerProfile": {
          "name": "John Doe",
          "username": "john_doe"
        }
      }
    ],
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}

Участник добавлен

{
  "id": "evt_group_participants_123",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_participants_update",
    "type": "group_participants_add",
    "status": "added",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "reason": "invite_link",
    "waId": "16315551111",
    "recipientUserId": "US.abc123",
    "parentRecipientUserId": "US.parent123",
    "addedParticipants": [
      {
        "input": "US.abc123",
        "waId": "16315551111",
        "recipientUserId": "US.abc123",
        "parentRecipientUserId": "US.parent123"
      }
    ],
    "customerProfile": {
      "name": "John Doe",
      "username": "john_doe"
    },
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}

Запрос на вступление создан

{
  "id": "evt_group_participants_124",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_participants_update",
    "type": "group_join_request_created",
    "status": "requested",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "reason": "admin_approval",
    "joinRequestId": "join-request-id",
    "waId": "16315551111",
    "recipientUserId": "US.abc123",
    "parentRecipientUserId": "US.parent123",
    "webhookTime": "2026-05-13T00:00:00.000Z",
    "customerProfile": {
      "name": "John Doe",
      "username": "john_doe"
    }
  }
}

Не удалось удалить участника

{
  "id": "evt_group_participants_125",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_participants_update",
    "type": "group_participants_remove",
    "requestId": "REQ_REMOVE",
    "status": "failed",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "initiatedBy": "business",
    "removedParticipants": [
      {
        "input": "16315551111"
      }
    ],
    "failedParticipants": [
      {
        "input": "16315552222",
        "errors": [
          {
            "code": 131212,
            "title": "Participant cannot be removed"
          }
        ]
      }
    ],
    "errors": [
      {
        "title": "Not all participants were removed"
      }
    ],
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}

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

HTTP/1.1 200 OK

Пошаговые сценарии см. в разделе аннотированные примеры.

Начало работы

Руководства

Конечные точки

Webhook reference

whatsapp.group.participants_update

Триггеры

Синтаксис

Параметры

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

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

whatsappGroup

Пример

​Триггеры

​Синтаксис

​Параметры

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

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

​whatsappGroup

​Пример

Триггеры

Синтаксис

Параметры

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

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

whatsappGroup

Пример