message.status

EVENTOmessage.statusdesde M3envelope v1

Status de mensagem enviada.

Quando é emitido

Acompanha as mensagens enviadas pela API: sent, delivered, read ou failed (com error no formato codigo: detalhe). Se um recibo chegar antes da confirmação do envio, delivered (ou read) pode chegar antes de message.sent, e o sent é omitido. played (M7) sai quando o contato reproduz um áudio de voz, vídeo ou mídia de visualização única; é o status mais alto (um read atrasado não o rebaixa). Mensagem apagada sai em message.revoked.

Campos de data

Campo	Tipo	Descrição
id	string	Id devolvido por POST /messages.
wa_message_id	string	Id no WhatsApp (opcional).
chat	string	JID do chat.
status	string	sent, delivered, read, played ou failed.
error	string	Motivo, em failed (opcional).

O envelope (id, type, version, instance_id, timestamp,data) está em Visão geral. Campos novos podem ser adicionados emdata sem mudar a versão: ignore os que não conhecer.

Exemplos

Lida

{
  "id": "evt_0f5c2a8e6d1b9374",
  "type": "message.status",
  "version": 1,
  "instance_id": "inst_7f3a9c2e5b1d4086",
  "timestamp": "2026-10-17T13:51:20.144Z",
  "data": {
    "id": "msg_a41c9e07d2b35f68",
    "wa_message_id": "3EB0A1B2C3D4E5F6A7B8C9",
    "chat": "5511999999999@s.whatsapp.net",
    "status": "read"
  }
}

Falhou

{
  "id": "evt_6d1a9e4c2f7b0583",
  "type": "message.status",
  "version": 1,
  "instance_id": "inst_7f3a9c2e5b1d4086",
  "timestamp": "2026-10-17T13:52:00.010Z",
  "data": {
    "id": "msg_0c5e8b2f9a7d4613",
    "chat": "5511888888888@s.whatsapp.net",
    "status": "failed",
    "error": "invalid_number: number is not on WhatsApp"
  }
}

Entrega e ordem

• Por webhook: pelo menos uma vez, com retry por até 24 horas. O mesmo evento pode chegar duas vezes: deduplique porX-LiteZap-Event-Id. Veja Entrega e retentativas.
• A ordem entre eventos não é garantida (retentativas reordenam): use timestamp.
• Por SSE: ao vivo, sem replay. Veja Tempo real com SSE.
• Para assinar só este tipo: "events": ["message.status"] no webhook, ou?types=message.status no SSE.

Relacionados: message.sent

Equivalente na Z-API: Status da mensagem.