> ## 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.lifecycle_update > Ocorre quando um grupo do WhatsApp é criado ou excluído, incluindo resultados bem-sucedidos e com falha. Use `whatsapp.group.lifecycle_update` para processar este evento em seu endpoint de webhook. ## Gatilhos Ocorre quando um grupo do WhatsApp é criado ou excluído, incluindo resultados bem-sucedidos e com falha. Inscreva-se em `whatsapp.group.lifecycle_update` quando você [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 espaços reservados; 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.lifecycle_update", "apiVersion": "", "createTime": "", "whatsappGroup": { "wabaId": "", "displayPhoneNumber": "", "phoneNumberId": "", "field": "", "type": "", "requestId": "", "status": "", "groupId": "", "inviteLink": "", "subject": "", "description": "", "joinApprovalMode": "", "webhookTime": "", "dedupeKey": "" } } ``` ## Parâmetros Valide o cabeçalho HTTP `YCloud-Signature` antes de processar o corpo JSON. Consulte [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.lifecycle_update`. | | `apiVersion` | string | Sim | A versão da API usada para renderizar este evento. | | `createTime` | string (date-time) | Sim | A data e hora em que este evento foi criado, formatada 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 específico do evento `whatsappGroup`. | Os quatro campos comuns do envelope são obrigatórios. Os campos do payload dependem da variante do evento. Em cada tabela de objeto, **Obrigatório** se aplica quando o objeto pai estiver 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 do webhook do WhatsApp. | | `phoneNumberId` | string | Não | ID do número de telefone do WhatsApp. | | `field` | string | Não | Campo do webhook do WhatsApp que gerou o evento do grupo.Valores: `group_lifecycle_update`, `group_participants_update`, `group_settings_update`, `group_status_update`, `messages`. | | `type` | string | Não | Tipo de evento específico do 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 do webhook de 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 está 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 para 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 único. | | `recipientUserId` | string | Não | ID de usuário no escopo da empresa (business-scoped) para um evento de participante único. | | `parentRecipientUserId` | string | Não | ID de usuário no escopo da empresa principal (parent business-scoped) para um evento de participante único. | | `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 para entrar 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 falharam ao serem 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 mensagem de grupo. | | `statuses` | object\[] | Não | Detalhes do status da mensagem de grupo. | | `webhookTime` | string (date-time) | Não | A hora em que o WhatsApp disparou 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 de 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 (business-scoped). | > | `parentRecipientUserId` | string | Não | ID de usuário no escopo da empresa principal (parent business-scoped). | > | `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 de 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 comercial (business-scoped user ID). | > | `parentRecipientUserId` | string | Não | ID de usuário com escopo comercial 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 comercial (business-scoped user ID). | > | `parentRecipientUserId` | string | Não | ID de usuário com escopo comercial 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 em texto para atualizações de assunto ou descrição. | > | `updateSuccessful` | boolean | Não | Indica 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 comercial (business-scoped user ID). | > | `parentRecipientUserId` | string | Não | ID de usuário com escopo comercial 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 com escopo de negócios do participante destinatário. | > | `parentRecipientUserId` | string | Não | ID de usuário pai com escopo de negócios do participante destinatário. | > | `conversation` | object | Não | Objeto de conversa do WhatsApp incluído nos webhooks de status de mensagem de grupo. | > | `pricing` | object | Não | Informações de preço incluídas nos webhooks de status de mensagem 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 | 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 de webhook.Valores: `group_marketing`, `group_utility`, `group_service`. | ## Exemplo O JSON a seguir é o corpo entregue ao seu receptor. IDs, números de telefone e outros valores de conta são ilustrativos. > [accordion] Evento de atualização do ciclo de vida de grupo do WhatsApp > > Exemplo de carga útil quando um grupo do WhatsApp é criado > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_group_lifecycle_123", > "type": "whatsapp.group.lifecycle_update", > "apiVersion": "v2", > "createTime": "2026-05-13T00:00:00.000Z", > "whatsappGroup": { > "wabaId": "123456789012345", > "displayPhoneNumber": "16315551111", > "phoneNumberId": "1234567890123456", > "field": "group_lifecycle_update", > "type": "group_create", > "requestId": "REQ_1", > "status": "created", > "groupId": "120363345678901234@g.us", > "inviteLink": "https://chat.whatsapp.com/AbCdEfGhIjK", > "subject": "New Purchase Inquiry", > "description": "Group for purchase inquiries.", > "joinApprovalMode": "auto_approve", > "webhookTime": "2026-05-13T00:00:00.000Z", > "dedupeKey": "123456789012345|REQ_1|group_lifecycle_update|group_create|created" > } > } > ``` > [accordion] Grupo criado > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_group_lifecycle_123", > "type": "whatsapp.group.lifecycle_update", > "apiVersion": "v2", > "createTime": "2026-05-13T00:00:00.000Z", > "whatsappGroup": { > "wabaId": "123456789012345", > "displayPhoneNumber": "16315551111", > "phoneNumberId": "1234567890123456", > "field": "group_lifecycle_update", > "type": "group_create", > "requestId": "REQ_1", > "status": "created", > "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE", > "inviteLink": "https://chat.whatsapp.com/AbCdEfGhIjK", > "subject": "New Purchase Inquiry", > "description": "Group for purchase inquiries.", > "joinApprovalMode": "auto_approve", > "webhookTime": "2026-05-13T00:00:00.000Z", > "dedupeKey": "123456789012345|REQ_1|group_lifecycle_update|group_create|created" > } > } > ``` > [accordion] Grupo excluído > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_group_lifecycle_124", > "type": "whatsapp.group.lifecycle_update", > "apiVersion": "v2", > "createTime": "2026-05-13T00:00:00.000Z", > "whatsappGroup": { > "wabaId": "123456789012345", > "field": "group_lifecycle_update", > "type": "group_delete", > "requestId": "REQ_DELETE", > "status": "deleted", > "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE", > "webhookTime": "2026-05-13T00:00:00.000Z" > } > } > ``` Após verificar a assinatura e aceitar o evento de forma duradoura, retorne uma resposta `2xx`. Processe tarefas lentas de forma assíncrona. ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} HTTP/1.1 200 OK ``` Para conferir explicações detalhadas sobre os cenários, consulte [exemplos anotados](https://docs.ycloud.com/pt/api-reference/guides/examples/webhook-examples/whatsapp-group-lifecycle-update-webhook-examples). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.