message.received

EVENTOmessage.receiveddesde M3envelope v1

Mensagem recebida.

Quando é emitido

Emitido para cada mensagem nova de outra pessoa (source: "contact"), em chat direto ou grupo. Mídia vem descrita em media, com url para baixar pela API (autenticada). Mensagens do histórico sincronizado no pareamento não geram este evento (só um history.synced), e uma mensagem que chega duas vezes (reconexão do worker) gera um único evento. Reações chegam como message.reaction.

Campos de data

Campo	Tipo	Descrição
id	string	Id LiteZap da mensagem no log.
wa_message_id	string	Id da mensagem no WhatsApp.
chat	string	JID do chat (pessoa ou grupo).
sender	string	JID de quem enviou (em grupos, o participante).
from_me	boolean	Sempre false aqui.
is_group	boolean	true em grupos.
push_name	string	Nome de perfil de quem enviou.
source	string	contact.
type	string	text, image, video, audio, document, sticker, location, contact...
text	string	Texto ou legenda.
media	object	id, kind, mime, size, file_name, seconds, ptt, url (opcional).
timestamp	string	Hora da mensagem (RFC 3339).

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

Texto

{
  "id": "evt_5f2c9a1b7d3e4f60",
  "type": "message.received",
  "version": 1,
  "instance_id": "inst_7f3a9c2e5b1d4086",
  "timestamp": "2026-10-17T13:45:00.123Z",
  "data": {
    "id": "msg_e29d4b8a0f6c1357",
    "wa_message_id": "3A9F2C7D1E0B4A5C6D7E",
    "chat": "[email protected]",
    "sender": "[email protected]",
    "from_me": false,
    "push_name": "Maria",
    "source": "contact",
    "type": "text",
    "text": "Oi, meu pedido já saiu?",
    "timestamp": "2026-10-17T13:45:00Z"
  }
}

Imagem com legenda

{
  "id": "evt_2d6a9f1c4e8b3075",
  "type": "message.received",
  "version": 1,
  "instance_id": "inst_7f3a9c2e5b1d4086",
  "timestamp": "2026-10-17T13:46:12.877Z",
  "data": {
    "id": "msg_4f0b7c2e9a1d6358",
    "wa_message_id": "3A1B5D9F2C7E4A0B8C6D",
    "chat": "[email protected]",
    "sender": "[email protected]",
    "from_me": false,
    "push_name": "Maria",
    "source": "contact",
    "type": "image",
    "text": "Foto do produto",
    "media": {
      "id": "med_5b8e1f3c9d2a7046",
      "kind": "image",
      "mime": "image/jpeg",
      "size": 182345,
      "url": "/v1/instances/inst_7f3a9c2e5b1d4086/media/med_5b8e1f3c9d2a7046"
    },
    "timestamp": "2026-10-17T13:46:12Z"
  }
}

Mensagem de voz

{
  "id": "evt_7a3d0f6b2c9e1484",
  "type": "message.received",
  "version": 1,
  "instance_id": "inst_7f3a9c2e5b1d4086",
  "timestamp": "2026-10-17T13:47:30.402Z",
  "data": {
    "id": "msg_9c2e5a8d1f4b7063",
    "wa_message_id": "3A7E2B9D4F1C6A0E5B8D",
    "chat": "[email protected]",
    "sender": "[email protected]",
    "from_me": false,
    "push_name": "Maria",
    "source": "contact",
    "type": "audio",
    "media": {
      "id": "med_1d6f3b9e4a2c8057",
      "kind": "audio",
      "mime": "audio/ogg; codecs=opus",
      "size": 23110,
      "seconds": 7,
      "ptt": true,
      "url": "/v1/instances/inst_7f3a9c2e5b1d4086/media/med_1d6f3b9e4a2c8057"
    },
    "timestamp": "2026-10-17T13:47:30Z"
  }
}

Texto em grupo

{
  "id": "evt_3e9b6d2a0f7c5148",
  "type": "message.received",
  "version": 1,
  "instance_id": "inst_7f3a9c2e5b1d4086",
  "timestamp": "2026-10-17T13:50:05.611Z",
  "data": {
    "id": "msg_6a1d8f3c0e5b9274",
    "wa_message_id": "3A0C4E8B2D6F1A9C7E3B",
    "chat": "[email protected]",
    "sender": "[email protected]",
    "from_me": false,
    "is_group": true,
    "push_name": "João",
    "source": "contact",
    "type": "text",
    "text": "Reunião às 15h",
    "timestamp": "2026-10-17T13:50:05Z"
  }
}

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.received"] no webhook, ou?types=message.received no SSE.

Relacionados: message.reaction · message.sent · history.synced

Equivalente na Z-API: Ao receber.