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.

Grupos

Em grupos, cada participante confirma separadamente. Em vez de um evento por participante, a API junta as confirmações de cada mensagem durante 60 segundos (contados da primeira, sem renovar) e envia um messages_update com type: "GroupReceipts":

  • um evento por mensagem: MessageIDs tem sempre um item;
  • event.Receipts lista quem confirmou, o estado (Delivered, Read ou Played) e o horário de cada um;
  • não há state, Sender nem Timestamp únicos: leia cada item de Receipts;
  • confirmações que chegam depois da janela saem num próximo evento da mesma mensagem;
  • IsGroup é true: quem usa o filtro isGroupYes não recebe esses eventos.

Confira type antes de processar: ReadReceipt para conversas individuais, GroupReceipts para grupos. A API não grava as confirmações em banco: se precisar do histórico, guarde os eventos. POST /message/status mostra as confirmações de uma mensagem, da memória da API ou do celular da conta. O status da mensagem de grupo segue o participante mais adiantado (pelo menos um recebeu, leu ou ouviu) e muda junto com o GroupReceipts.

Habilitar este evento

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

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.

CampoTipoSignificado
EventTypestringObrigatório. Tipo de evento, por exemplo connection ou messages.
ownerstringObrigatório. Consulte o objeto ou exemplo correspondente.
tokenstringObrigatório. Token da instância; dado sensível.
BaseUrlstringObrigatório. Consulte o objeto ou exemplo correspondente.
instanceNamestringConsulte o objeto ou exemplo correspondente.
typestringOrigem do evento: ReadReceipt nas conversas individuais; GroupReceipts no lote de confirmações de uma mensagem de grupo.
statestringEstado normalizado aplicado às mensagens (ReadReceipt). Ausente em GroupReceipts.
eventobjectRecibo e mensagens afetadas.
event.chatidstringJID da conversa, quando resolvido.
event.chatlidstring / nullLID da conversa; pode ser ausente ou null.
event.sender_pnstring / nullJID por telefone, quando conhecido.
event.sender_lidstring / nullIdentificador LID, quando conhecido.
event.ChatstringJID da conversa.
event.SenderstringJID do emissor do recibo. Ausente em GroupReceipts.
event.MessageIDsarray / nullMensagens afetadas. Em GroupReceipts, sempre uma.
event.TimestampintegerSegundos Unix no fluxo de recibos. Ausente em GroupReceipts; use o timestamp de cada item.
event.TypestringEstado do recibo; GroupReceipts no lote de grupo.
event.IsFromMebooleanOrigem da mensagem.
event.IsGroupbooleanConversa de grupo.
event.ReceiptsarraySó em GroupReceipts: confirmações dos participantes nesta janela, em ordem de horário.

Exemplos de entrega

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

Recibo de leitura

{
  "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
  }
}

Confirmações de grupo (GroupReceipts)

{
  "EventType": "messages_update",
  "owner": "5511999999999",
  "token": "INSTANCE_TOKEN",
  "BaseUrl": "https://seu-servidor.example",
  "instanceName": "Atendimento",
  "type": "GroupReceipts",
  "event": {
    "Chat": "120363000000001@g.us",
    "chatid": "120363000000001@g.us",
    "IsFromMe": false,
    "IsGroup": true,
    "MessageIDs": [
      "MSG_EXEMPLO"
    ],
    "Type": "GroupReceipts",
    "Receipts": [
      {
        "participant": "5511911110000@s.whatsapp.net",
        "participant_pn": "5511911110000@s.whatsapp.net",
        "participant_lid": "300001@lid",
        "state": "Delivered",
        "timestamp": 1788868801
      },
      {
        "participant": "5511922220000@s.whatsapp.net",
        "participant_pn": "5511922220000@s.whatsapp.net",
        "participant_lid": "300002@lid",
        "state": "Delivered",
        "timestamp": 1788868803
      },
      {
        "participant": "5511911110000@s.whatsapp.net",
        "participant_pn": "5511911110000@s.whatsapp.net",
        "participant_lid": "300001@lid",
        "state": "Read",
        "timestamp": 1788868820
      }
    ]
  }
}

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.

Referências