message.received

Se envía cuando: Llega un mensaje entrante a una de tus instancias: texto o multimedia, de una persona o de un grupo.

Qué trae data: Un objeto message con direction: "inbound" y status: "received". En un mensaje de grupo, group_id trae el id público del grupo (grp_...) y from el número de quien escribió. Si el mensaje trae un archivo, media.available indica que puedes descargarlo con GET /messages/{message}/media; el archivo no viene incluido en el evento.

Para qué sirve: Guardar la respuesta de un cliente, abrir una conversación en tu sistema o disparar un flujo propio.

Ejemplo

El cuerpo que recibe tu servidor (datos ficticios):

{
  "id": "evt_01EXAMPLE00000000000000001",
  "type": "message.received",
  "created_at": "2026-01-01T12:00:00.000000Z",
  "workspace_id": "ten_01EXAMPLE00000000000000000",
  "data": {
    "message": {
      "id": "msg_01EXAMPLE00000000000000000",
      "instance_id": "ins_01EXAMPLE00000000000000000",
      "direction": "inbound",
      "type": "text",
      "status": "received",
      "to": null,
      "from": "5255000000002",
      "group_id": null,
      "text": "Hello, do you ship to Monterrey?",
      "caption": null,
      "media": null,
      "error": null,
      "created_at": "2026-01-01T11:59:59+00:00",
      "queued_at": null,
      "sent_at": null,
      "delivered_at": null,
      "read_at": null,
      "failed_at": null,
      "received_at": "2026-01-01T11:59:59+00:00"
    }
  }
}

Todos los eventos comparten el mismo sobre (id, type, created_at, workspace_id, data) y los mismos headers de firma. Cómo verificarla, qué responder y cómo se reintenta: Webhooks.