Alterações de grupos

Evento: groups · Transporte: POST para o seu receptor

Acompanhe alterações de metadados e participantes de grupos.

Variações

O fluxo pode usar type: Group para alterações de informações e type: JoinedGroup para entrada em grupo. O conteúdo de event varia com a alteração. Join, Leave, Promote e Demote descrevem participantes afetados; campos ausentes ou nulos não significam, por si só, que todos foram removidos.

Use event.JID ou o identificador normalizado disponível na raiz para correlacionar o grupo. Os arrays podem incluir projeções PN/LID. Consulte /group/info quando precisar do estado atual completo, em vez de reconstruí-lo a partir de um único evento parcial.

Habilitar este evento

Adicione groups à lista events do webhook da instância. Preserve os outros eventos de que sua integração precisa.

{
  "enabled": true,
  "url": "https://seu-sistema.example/hooks/whatsapp",
  "events": [
    "groups"
  ]
}

Envie essa configuração para POST /webhook, usando o header token. O JSON acima configura a assinatura; os exemplos de entrega abaixo são o que seu servidor recebe.

Campos do payload

O envelope comum vem na raiz. Campos condicionais podem estar ausentes ou nulos conforme o evento; não use a tabela como obrigação de presença de todos os campos.

Campo	Tipo	Significado
`EventType`	string	Obrigatório. Tipo de evento, por exemplo connection ou messages.
`owner`	string	Obrigatório. Consulte o objeto ou exemplo correspondente.
`token`	string	Obrigatório. Token da instância; dado sensível.
`BaseUrl`	string	Obrigatório. Consulte o objeto ou exemplo correspondente.
`instanceName`	string	Consulte o objeto ou exemplo correspondente.
`type`	string	Group ou JoinedGroup, conforme a origem.
`chatid`	string	JID da conversa, quando resolvido.
`chatlid`	string / null	LID da conversa; pode ser ausente ou null.
`sender_pn`	string / null	JID por telefone, quando conhecido.
`sender_lid`	string / null	Identificador LID, quando conhecido.
`event`	object	Mudança de grupo.
`event.JID`	string	JID do grupo.
`event.Sender`	string / null	Participante associado à alteração, quando disponível.
`event.Timestamp`	string	Data/hora da alteração.
`event.Name`	object / null	Alteração de nome.
`event.Name.Name`	string	Nome informado.
`event.Topic`	object / null	Alteração de descrição.
`event.Topic.Topic`	string	Descrição informada.
`event.Join`	array / null	Participantes afetados por esta alteração.
`event.Leave`	array / null	Participantes afetados por esta alteração.
`event.Promote`	array / null	Participantes afetados por esta alteração.
`event.Demote`	array / null	Participantes afetados por esta alteração.

Exemplos de entrega

Exemplos ilustrativos com identificadores fictícios. O conteúdo específico e os campos opcionais variam.

Alteração do nome do grupo

{
  "EventType": "groups",
  "owner": "5511999999999",
  "token": "INSTANCE_TOKEN",
  "BaseUrl": "https://seu-servidor.example",
  "instanceName": "Atendimento",
  "type": "Group",
  "event": {
    "JID": "120363000000000001@g.us",
    "Sender": "5511888888888@s.whatsapp.net",
    "Timestamp": "2026-09-08T12:00:00Z",
    "Name": {
      "Name": "Equipe de atendimento"
    },
    "Join": [],
    "Leave": [],
    "Promote": [],
    "Demote": []
  }
}

Responder ao webhook

Seu receptor deve aceitar o POST JSON e devolver uma resposta 2xx rapidamente, após validar e registrar o recebimento. O corpo da resposta não é um comando para a API. Processe trabalho demorado separadamente.

O worker não repete automaticamente uma entrega HTTP malsucedida. Consulte diagnóstico de webhooks e implemente a reconciliação necessária. Eventos repetidos ou fora de ordem ainda precisam ser tolerados pelo receptor.