# 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.

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

Envie essa configuração para [POST /webhook](/reference/updateWebhook.md), 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

```json
{
  "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](/docs/integrations-webhooks#diagnostico) e implemente a reconciliação necessária. Eventos repetidos ou fora de ordem ainda precisam ser tolerados pelo receptor.

## Referências

- [Introdução, configuração e catálogo](/docs/integrations-webhooks)
- [Autenticação](/docs/authentication)
- [Contrato OpenAPI completo](/openapi-bundled.json)