Contatos

Evento: contacts · Transporte: POST para o seu receptor

Acompanhe alterações de contatos recebidas pela sessão.

Como interpretar

event.JID identifica o contato e event.Action contém a atualização recebida, como nomes da agenda. O evento não significa que uma nova conversa foi criada.

Alterações provenientes do full sync podem ser absorvidas pelo processamento de histórico, sem uma notificação individual de contato. Para uma visão inicial, consulte a listagem de contatos e processe os eventos posteriores como atualizações.

Habilitar este evento

Adicione contacts à 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": [
    "contacts"
  ]
}

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	O fluxo de contato usa Contact.
`event`	object	Atualização de contato.
`event.JID`	string	JID do contato.
`event.Timestamp`	string	Data/hora informada no evento.
`event.FromFullSync`	boolean	Origem em sincronização completa, quando presente.
`event.Action`	object	Dados alterados do contato.
`event.Action.fullName`	string	Nome completo disponível.
`event.Action.firstName`	string	Primeiro nome disponível.
`event.Action.lidJID`	string	Identificador LID, quando disponível.
`event.Action.saveOnPrimaryAddressbook`	boolean	Informação de salvamento na agenda principal, quando presente.

Exemplos de entrega

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

Alteração de nome

{
  "EventType": "contacts",
  "owner": "5511999999999",
  "token": "INSTANCE_TOKEN",
  "BaseUrl": "https://seu-servidor.example",
  "instanceName": "Atendimento",
  "type": "Contact",
  "event": {
    "JID": "5511888888888@s.whatsapp.net",
    "Timestamp": "2026-09-08T12:00:00Z",
    "FromFullSync": false,
    "Action": {
      "fullName": "Contato de exemplo",
      "firstName": "Contato"
    }
  }
}

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.