# Entrega e leitura

**Evento:** `messages_update` · **Transporte:** POST para o seu receptor

Acompanhe atualizações de estado de mensagens, como recibos de entrega e leitura.

## Como correlacionar

`event.MessageIDs` pode conter vários IDs. Aplique o estado recebido a cada mensagem correspondente da mesma instância/conversa. Não trate o evento como uma mensagem nova.

A grafia dos campos é relevante: `MessageIDs`, `Timestamp`, `Type`, `IsFromMe` e `IsGroup` usam maiúsculas. Os campos normalizados `chatid`, `sender_pn` e `sender_lid` usam minúsculas.

`event.Timestamp` do fluxo de recibos usa segundos Unix. Isso é diferente de `message.messageTimestamp`, que usa milissegundos. Eventos podem chegar fora da ordem esperada; preserve sua regra de progressão de estado.

## Habilitar este evento

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

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 | Origem do evento; o fluxo de recibos usa ReadReceipt. |
| `state` | string | Estado normalizado aplicado às mensagens. |
| `event` | object | Recibo e mensagens afetadas. |
| `event.chatid` | string | JID da conversa, quando resolvido. |
| `event.chatlid` | string / null | LID da conversa; pode ser ausente ou null. |
| `event.sender_pn` | string / null | JID por telefone, quando conhecido. |
| `event.sender_lid` | string / null | Identificador LID, quando conhecido. |
| `event.Chat` | string | JID da conversa. |
| `event.Sender` | string | JID do emissor do recibo. |
| `event.MessageIDs` | array / null | Mensagens afetadas. |
| `event.Timestamp` | integer | Segundos Unix no fluxo de recibos. |
| `event.Type` | string | Estado do recibo. |
| `event.IsFromMe` | boolean | Origem da mensagem. |
| `event.IsGroup` | boolean | Conversa de grupo. |

## Exemplos de entrega

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

### Recibo de leitura

```json
{
  "EventType": "messages_update",
  "owner": "5511999999999",
  "token": "INSTANCE_TOKEN",
  "BaseUrl": "https://seu-servidor.example",
  "instanceName": "Atendimento",
  "type": "ReadReceipt",
  "state": "Read",
  "event": {
    "Chat": "5511888888888@s.whatsapp.net",
    "chatid": "5511888888888@s.whatsapp.net",
    "chatlid": null,
    "Sender": "5511888888888@s.whatsapp.net",
    "sender_pn": "5511888888888@s.whatsapp.net",
    "sender_lid": null,
    "MessageIDs": [
      "MSG_EXEMPLO"
    ],
    "Timestamp": 1788868800,
    "Type": "Read",
    "IsFromMe": true,
    "IsGroup": false
  }
}
```

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