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.

wa_flow_response_received trae además flow_id y bsuids

Los dos están siempre en este evento. wa_flow_sent no los trae.

flow_id llega en null cuando no pudimos resolverlo: lo resolvemos correlacionando el
flow_token —que viaja dentro del JSON de message— con el envío que lo originó, así que si
ese envío no está registrado el campo va vacío. En ese caso el flow_token del propio
message sigue siendo la llave para correlacionar del lado de su integración.

bsuids responde «¿por cuál de mis números me escribió esta persona?». Un contacto que oculta
su teléfono tiene un identificador distinto por cada portafolio de negocio de Meta, y
bsuid (el campo suelto) trae solo el de esta conversación:

"wa_id": "MX.7788990011223344",
"bsuid": "MX.7788990011223344",
"wa_username": "ana.gomez",
"flow_id": "9876543210987654",
"bsuids": [
  {
    "bsuid": "CO.1234567890123456",
    "line": { "display_name": "Ventas Colombia", "phone_number": "+57 300 123 4567", "phone_id": "109876543210987" }
  },
  { "bsuid": "MX.7788990011223344", "line": null }
]

line viene en null cuando no sabemos por qué línea se observó ese identificador — pasa con
los que aprendimos antes de guardar ese dato. phone_id es el id de la línea en Meta, el
mismo que usted ve en sus propios webhooks de Meta. La lista llega vacía ([]) si el contacto
ya no existe en su cuenta.

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