> ## 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.participants_update > Ocorre quando os participantes de um grupo do WhatsApp ou as solicitações de entrada são atualizados. 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](https://docs.ycloud.com/pt/api-reference/guides/api-fundamentals/configure-webhooks.md). ## 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. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "id": "", "type": "whatsapp.group.participants_update", "apiVersion": "", "createTime": "", "whatsappGroup": { "wabaId": "", "field": "", "type": "", "status": "", "groupId": "", "waId": "", "recipientUserId": "", "parentRecipientUserId": "", "customerProfile": { "name": "", "username": "" }, "addedParticipants": [ { "input": "", "waId": "", "recipientUserId": "", "parentRecipientUserId": "", "customerProfile": { "name": "", "username": "" } } ], "webhookTime": "" } } ``` ## Parâmetros Valide o cabeçalho HTTP `YCloud-Signature` antes de processar o corpo JSON. Consulte a [validação de assinatura](https://docs.ycloud.com/pt/api-reference/guides/api-fundamentals/configure-webhooks.md). ### 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](https://datatracker.ietf.org/doc/html/rfc3339). 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. | > [accordion] 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. | > [accordion] 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. | > [accordion] 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. | > [accordion] 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. | > [accordion] 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. | > [accordion] 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. | > [accordion] 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. | > [accordion] 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. | > [accordion] 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. | > [accordion] 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. | > [accordion] 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. | > [accordion] 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. | > [accordion] whatsappGroup.statuses\[].conversation.origin > > | Parâmetro | Tipo | Obrigatório | Descrição | > | - | - | - | - | > | `type` | string | Não | Tipo de origem da conversa. | > [accordion] 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. > [accordion] Evento de atualização de participantes do grupo do WhatsApp > > Exemplo de payload quando participantes do grupo do WhatsApp são adicionados > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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" > } > } > ``` > [accordion] Participante adicionado > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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" > } > } > ``` > [accordion] Solicitação de entrada criada > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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" > } > } > } > ``` > [accordion] Falha na remoção do participante > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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 theme={"theme":{"light":"github-light","dark":"github-dark"}} HTTP/1.1 200 OK ``` Para conferir tutoriais passo a passo de cenários, consulte os [exemplos anotados](https://docs.ycloud.com/pt/api-reference/guides/examples/webhook-examples/whatsapp-group-participants-update-webhook-examples). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.