whatsapp.group.participants_update

Use whatsapp.group.participants_update para manipular este evento no seu endpoint de webhook.

Gatilhos

Ocorre quando os participantes de um grupo do WhatsApp ou as solicitações de entrada são atualizados. Inscreva-se em whatsapp.group.participants_update ao configurar seu endpoint de webhook.

Sintaxe

A YCloud envia uma solicitação HTTP POST para a URL de webhook configurada. A estrutura a seguir mostra uma variante de payload. Os valores entre colchetes angulares são marcadores; seus tipos estão listados em Parâmetros. Os campos opcionais e outras variantes são descritos abaixo.

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

Parâmetros

Valide o cabeçalho HTTP YCloud-Signature antes de processar o corpo JSON. Consulte a validação de assinatura.

Envelope do evento

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	ID exclusivo do evento. Tamanho mínimo: `6`. Tamanho máximo: `128`.
`type`	string	Sim	Sempre `whatsapp.group.participants_update`.
`apiVersion`	string	Sim	A versão da API usada para renderizar este evento.
`createTime`	string (date-time)	Sim	O momento em que este evento foi criado, formatado em RFC 3339. Ex.: `2022-06-01T12:00:00.000Z`.

Payload do evento

Parâmetro	Tipo	Obrigatório	Descrição
`whatsappGroup`	object	Não	Payload de `whatsappGroup` específico do evento.

Os quatro campos comuns do envelope são obrigatórios. Os campos do payload dependem da variante do evento. Em cada tabela de objetos, Obrigatório se aplica quando o objeto pai está presente. Campos opcionais podem ser omitidos; um exemplo não torna um campo obrigatório.

whatsappGroup

Parâmetro	Tipo	Obrigatório	Descrição
`wabaId`	string	Não	ID da conta do WhatsApp Business.
`displayPhoneNumber`	string	Não	O número de telefone de exibição dos metadados de webhook do WhatsApp.
`phoneNumberId`	string	Não	ID do número de telefone do WhatsApp.
`field`	string	Não	Campo de webhook do WhatsApp que gerou o evento de grupo. Valores: `group_lifecycle_update`, `group_participants_update`, `group_settings_update`, `group_status_update`, `messages`.
`type`	string	Não	Tipo de evento específico de grupo do WhatsApp. Valores: `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	Não	O ID da solicitação retornado por uma operação assíncrona da API de grupos.
`status`	string	Não	Status de webhook do grupo do WhatsApp. Valores: `created`, `failed`, `deleted`, `added`, `removed`, `left`, `requested`, `revoked`, `updated`, `suspended`, `suspend_cleared`, `sent`, `delivered`, `read`, `expired`.
`groupId`	string	Não	ID do grupo do WhatsApp.
`messageId`	string	Não	ID da mensagem de grupo da YCloud. Presente apenas quando o evento de status estiver vinculado a uma mensagem de grupo de saída salva.
`inviteLink`	string	Não	O link de convite do grupo.
`reason`	string	Não	O motivo de um evento de participante, solicitação de entrada ou remoção.
`initiatedBy`	string	Não	Indica quem iniciou um evento de remoção de participante. Valores: `business`, `participant`.
`joinRequestId`	string	Não	O ID da solicitação de entrada.
`waId`	string	Não	ID de usuário do WhatsApp para um evento de participante individual.
`recipientUserId`	string	Não	ID de usuário no escopo da empresa para um evento de participante individual.
`parentRecipientUserId`	string	Não	ID de usuário pai com escopo comercial para um evento de participante individual.
`customerProfile`	object	Não	Informações de perfil de cliente do WhatsApp.
`subject`	string	Não	O assunto do grupo.
`description`	string	Não	A descrição do grupo.
`joinApprovalMode`	string	Não	Modo de aprovação de entrada no grupo do WhatsApp. `approval_required`: Novos membros devem ser aprovados antes de entrar. `auto_approve`: Novos membros podem entrar sem aprovação.
`addedParticipants`	object[]	Não	Participantes adicionados ao grupo.
`removedParticipants`	object[]	Não	Participantes removidos do grupo.
`failedParticipants`	object[]	Não	Participantes que não puderam ser adicionados ou removidos.
`settings`	object[]	Não	Detalhes da atualização das configurações do grupo.
`errors`	object[]	Não	Erros retornados pelo WhatsApp.
`contacts`	object[]	Não	Contatos incluídos nos webhooks de status de mensagens de grupo.
`statuses`	object[]	Não	Detalhes do status da mensagem de grupo.
`webhookTime`	string (date-time)	Não	O momento em que o WhatsApp acionou este webhook.
`dedupeKey`	string	Não	Chave de idempotência para desduplicação de eventos de webhook de grupo.

whatsappGroup.customerProfile

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Não	Nome do perfil do WhatsApp.
`username`	string	Não	Nome de usuário do WhatsApp.

whatsappGroup.addedParticipants[]

Parâmetro	Tipo	Obrigatório	Descrição
`input`	string	Não	A entrada original do participante.
`waId`	string	Não	ID de usuário do WhatsApp.
`recipientUserId`	string	Não	ID de usuário no escopo da empresa.
`parentRecipientUserId`	string	Não	ID de usuário pai com escopo comercial.
`customerProfile`	object	Não	Informações de perfil de cliente do WhatsApp.
`errors`	object[]	Não	Erros retornados pelo WhatsApp para este participante.

whatsappGroup.addedParticipants[].customerProfile

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Não	Nome do perfil do WhatsApp.
`username`	string	Não	Nome de usuário do WhatsApp.

whatsappGroup.removedParticipants[]

Parâmetro	Tipo	Obrigatório	Descrição
`input`	string	Não	A entrada original do participante.
`waId`	string	Não	ID de usuário do WhatsApp.
`recipientUserId`	string	Não	ID de usuário com escopo de negócios (Business-scoped user ID).
`parentRecipientUserId`	string	Não	ID de usuário com escopo de negócios pai.
`customerProfile`	object	Não	Informações de perfil de cliente do WhatsApp.
`errors`	object[]	Não	Erros retornados pelo WhatsApp para este participante.

whatsappGroup.removedParticipants[].customerProfile

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Não	Nome de perfil do WhatsApp.
`username`	string	Não	Nome de usuário do WhatsApp.

whatsappGroup.failedParticipants[]

Parâmetro	Tipo	Obrigatório	Descrição
`input`	string	Não	A entrada original do participante.
`waId`	string	Não	ID de usuário do WhatsApp.
`recipientUserId`	string	Não	ID de usuário com escopo de negócios (Business-scoped user ID).
`parentRecipientUserId`	string	Não	ID de usuário com escopo de negócios pai.
`customerProfile`	object	Não	Informações de perfil de cliente do WhatsApp.
`errors`	object[]	Não	Erros retornados pelo WhatsApp para este participante.

whatsappGroup.failedParticipants[].customerProfile

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Não	Nome de perfil do WhatsApp.
`username`	string	Não	Nome de usuário do WhatsApp.

whatsappGroup.settings[]

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Não	Nome da configuração. Valores: `profile_picture`, `group_subject`, `group_description`.
`text`	string	Não	Valor de texto para atualizações de assunto ou descrição.
`updateSuccessful`	boolean	Não	Se a atualização da configuração foi bem-sucedida.
`mimeType`	string	Não	Tipo MIME para atualizações de foto de perfil.
`sha256`	string	Não	Hash SHA-256 para atualizações de foto de perfil.
`errors`	object[]	Não	Erros retornados pelo WhatsApp para esta configuração.

whatsappGroup.contacts[]

Parâmetro	Tipo	Obrigatório	Descrição
`customerProfile`	object	Não	Informações de perfil de cliente do WhatsApp.
`waId`	string	Não	ID de usuário do WhatsApp.
`recipientUserId`	string	Não	ID de usuário com escopo de negócios (Business-scoped user ID).
`parentRecipientUserId`	string	Não	ID de usuário com escopo de negócios pai.

whatsappGroup.contacts[].customerProfile

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Não	Nome de perfil do WhatsApp.
`username`	string	Não	Nome de usuário do WhatsApp.

whatsappGroup.statuses[]

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	ID da mensagem do WhatsApp.
`status`	string	Não	Status da mensagem. Valores: `sent`, `delivered`, `read`, `failed`, `expired`.
`timestamp`	integer (int64)	Não	Carimbo de data/hora Unix indicando quando o status da mensagem foi atualizado.
`recipientId`	string	Não	ID do grupo destinatário.
`recipientType`	string	Não	Tipo de destinatário. Valores: `group`.
`recipientParticipantId`	string	Não	ID de usuário do WhatsApp do participante destinatário.
`recipientUserId`	string	Não	ID de usuário no escopo da empresa do participante destinatário.
`parentRecipientUserId`	string	Não	ID de usuário pai no escopo da empresa do participante destinatário.
`conversation`	object	Não	Objeto de conversa do WhatsApp incluído nos webhooks de status de mensagens de grupo.
`pricing`	object	Não	Informações de preço incluídas nos webhooks de status de mensagens de grupo.
`errors`	object[]	Não	Erros retornados pelo WhatsApp.

whatsappGroup.statuses[].conversation

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	ID da conversa.
`expirationTimestamp`	integer (int64)	Não	Carimbo de data/hora Unix indicando quando a conversa expira.
`origin`	object	Não	Os campos do objeto estão listados abaixo.

whatsappGroup.statuses[].conversation.origin

Parâmetro	Tipo	Obrigatório	Descrição
`type`	string	Não	Tipo de origem da conversa.

whatsappGroup.statuses[].pricing

Parâmetro	Tipo	Obrigatório	Descrição
`billable`	boolean	Não	Indica se a mensagem é faturável.
`pricingModel`	string	Não	Modelo de preço.
`type`	string	Não	Tipo de preço.
`category`	string	Não	Categoria bruta de preço de grupo informada pela Meta. A YCloud não expõe o mapeamento interno do MM Lite neste campo do webhook. Valores: `group_marketing`, `group_utility`, `group_service`.

Exemplo

O JSON a seguir é o corpo entregue ao seu destinatário. IDs, números de telefone e outros valores de conta são meramente ilustrativos.

Evento de atualização de participantes do grupo do WhatsApp

Exemplo de payload quando participantes do grupo do WhatsApp são adicionados

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

Participante adicionado

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

Solicitação de entrada criada

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

Falha na remoção do participante

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

Após verificar a assinatura e aceitar o evento de forma duradoura, retorne uma resposta 2xx. Processe trabalhos demorados de forma assíncrona.

HTTP/1.1 200 OK

Para conferir tutoriais passo a passo de cenários, consulte os exemplos anotados.

Primeiros passos

Guias

Endpoints

Webhook reference

whatsapp.group.participants_update

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

whatsappGroup

Exemplo

​Gatilhos

​Sintaxe

​Parâmetros

​Envelope do evento

​Payload do evento

​whatsappGroup

​Exemplo

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

whatsappGroup

Exemplo