Webhooks — Eventos de mensaje

Es la familia que cubre la conversación en sí: lo que entra, lo que sale y qué pasó con
cada envío.

Los seis se filtran por línea: solo recibe los de los números que marcó al configurar el
webhook.

Campos garantizados

Estos campos están siempre, con null cuando no hay valor:

⚠️

data es un campo interno de Wasapi, no JSON.

Viene vacío en la mayoría de los mensajes y, cuando trae algo, su formato no forma parte
del contrato y puede cambiar sin aviso. No dependa de él. Para adjuntos use filename
y caption.

Valores de message_type

Pueden aparecer valores nuevos: Meta agrega tipos. Trate un valor desconocido como genérico
en vez de rechazar el evento.

Campos extra, según el camino

Además del piso garantizado, cada evento puede traer campos propios. No están declarados y
pueden faltar: trátelos como opcionales.

Ejemplo — receive_message

{
  "event": "receive_message",
  "data": {
    "id": 900001,
    "user_id": 1234,
    "sender_id": null,
    "from_id": 42,
    "message": "Hola, quiero información de precios",
    "type": "in",
    "message_type": "text",
    "wa_id": "573001234567",
    "wam_id": "wamid.HBgMNTczMDAxMjM0NTY3FQIAEhgU…",
    "context_wam_id": null,
    "status": "n/a",
    "caption": null,
    "filename": null,
    "data": "",
    "reactions": null,
    "origin": "webhook",
    "created_at": "2026-08-07T15:04:11.000000Z",
    "updated_at": "2026-08-07T15:04:11.000000Z",
    "deleted_at": null,
    "bsuid": null,
    "wa_username": null,
    "version": 1
  }
}

Ejemplo — status_message con fallo

{
  "event": "status_message",
  "data": {
    "id": 900002,
    "user_id": 1234,
    "from_id": 42,
    "wa_id": "573001234567",
    "wam_id": "wamid.HBgMNTczMDAxMjM0NTY3FQIAERgS…",
    "type": "out",
    "message_type": "template",
    "status": "failed",
    "error_code": 131047,
    "error_message": "Re-engagement message",
    "bsuid": null,
    "wa_username": null,
    "version": 1
  }
}

status_message es el único evento que le avisa que un envío no llegó. Si le importa la
entrega, actívelo.

send_bot_message tiene el payload anidado

Es la excepción de la familia: trae dos mensajes, el del contacto y la respuesta del bot.

{
  "event": "send_bot_message",
  "data": {
    "user": {
      "id": 900003,
      "type": "in",
      "message": "1",
      "wa_id": "573001234567",
      "bsuid": null,
      "wa_username": null,
      "...": "el resto del piso garantizado"
    },
    "bot": {
      "id": 900004,
      "type": "out",
      "message": "Perfecto, le comparto el catálogo 👇",
      "wa_id": "573001234567",
      "bsuid": null,
      "wa_username": null,
      "...": "el resto del piso garantizado"
    },
    "version": 1
  }
}

Cada uno de los dos objetos cumple el piso garantizado por su cuenta. version va en la
raíz, no dentro de user ni de bot.

// El acceso NO es data['message'], sino:
$textoDelContacto = $data['user']['message'] ?? null;
$respuestaDelBot  = $data['bot']['message'] ?? null;

Notas de comportamiento

receive_message no distingue de qué contacto viene por sender_id

sender_id es siempre null en los entrantes: identifica al agente que envía, no al
contacto. Para saber de quién es el mensaje use wa_id (más bsuid / wa_username).

Los mensajes de tipo system también disparan eventos

Wasapi registra notas internas —asignación de agente, cierre de conversación— como mensajes
con type: "system" y message_type: "system". Si su integración solo quiere conversación
real, fíltrelos:

if ($data['type'] === 'system') {
    return; // nota interna, no es un mensaje de la conversación
}

origin le dice quién originó el mensaje

Útil para no reprocesar sus propios envíos: un mensaje que usted mandó por la API vuelve
como send_message con origin: "api".

Ver también

• Identidad del contacto — wa_id no siempre es un teléfono
• Introducción — reintentos e idempotencia