Webhooks — Eventos de Instagram y Messenger

Son los eventos de las conversaciones de Instagram y Facebook Messenger. Tienen su
propio formato, distinto del de WhatsApp, y se filtran por canal social: al configurar
el webhook usted elige de qué páginas o cuentas quiere recibirlos.

📘

Un webhook de WhatsApp nunca recibe estos eventos, y un webhook social nunca recibe
los de WhatsApp. Si atiende los dos tipos de canal, configure un webhook para cada uno.

Cómo se configura

1. Entre a Configuración → Desarrolladores → Webhooks en la plataforma.
2. Elija uno de los cuatro eventos. Solo aparecen si su plan incluye los canales sociales.
3. Marque al menos un canal. El canal es obligatorio: un webhook sin canales no recibe
   nada.

⚠️ Si conecta un canal nuevo, no queda suscrito automáticamente, igual que pasa con las
líneas de WhatsApp. Si desconecta un canal y lo vuelve a conectar, conserva sus webhooks.

Forma del evento

Los cuatro comparten el mismo envoltorio y los mismos bloques:

{
  "event": "social_message_received",
  "data": {
    "version": 1,
    "channel": {
      "uuid": "5f1c2e7a-0000-4000-8000-000000000042",
      "type": "instagram",
      "name": "Tienda Ejemplo",
      "username": "tiendaejemplo"
    },
    "conversation": {
      "uuid": "9b7d4c11-0000-4000-8000-000000000987",
      "status": "hold",
      "agent_id": null,
      "external_user_id": "1784100000000000",
      "window_expires_at": "2026-09-25T14:03:00Z"
    },
    "contact": {
      "uuid": "3a2b1c0d-0000-4000-8000-000000654321",
      "first_name": "Ana",
      "last_name": null,
      "email": null,
      "labels": [],
      "custom_fields": [],
      "is_new_contact": true
    },
    "message": {
      "id": 900042,
      "external_id": "m_AbCdEf0123456789",
      "direction": "in",
      "origin": null,
      "type": "text",
      "body": "Hola, ¿tienen talla M?",
      "attachments": [],
      "status": "sent",
      "error_message": null,
      "sent_at": "2026-09-24T14:03:00Z",
      "created_at": "2026-09-24T14:03:00Z"
    }
  }
}

Bloques

• labels es una lista de {id, title, color}, y custom_fields una lista de {name, value}.
• attachments es una lista de {type, url, mime, name}.
• is_new_contact es true solo en social_message_received, cuando ese mensaje creó el
  contacto. En los demás eventos siempre es false.
• Todas las fechas van en ISO 8601, en UTC, terminadas en Z.

⚠️ external_user_id es por página. Meta le da al mismo cliente un identificador
distinto en cada página o cuenta (PSID en Messenger, IGSID en Instagram). No lo use para
unir un cliente entre dos canales: para eso está contact.uuid.

Valores de origin

En los mensajes entrantes origin es null. En los salientes indica quién lo envió:

Los mensajes enviados desde Meta Business Suite pueden llegar unos 30 segundos después
de enviados: Wasapi espera a confirmar que no son un envío propio.

social_message_status

Llega uno por mensaje que pasa a leído. Si el cliente abre la conversación y lee cinco
mensajes suyos a la vez, recibe cinco eventos, cada uno con su message.

Meta no informa el estado «entregado» en estos canales. El único cambio de estado posible es
de sent a read.

social_message_sent con error

Si el envío falla, el evento igual llega, con message.status en failed y el motivo en
message.error_message. Así su integración se entera también de lo que no salió.

social_conversation_updated

En lugar de message trae un bloque change:

{
  "event": "social_conversation_updated",
  "data": {
    "version": 1,
    "channel": { "...": "igual que arriba" },
    "conversation": {
      "uuid": "9b7d4c11-0000-4000-8000-000000000987",
      "status": "open",
      "agent_id": 1234,
      "external_user_id": "1784100000000000",
      "window_expires_at": "2026-09-25T14:03:00Z"
    },
    "contact": { "...": "igual que arriba" },
    "change": {
      "actor": "agent",
      "previous_status": "hold",
      "previous_agent_id": null
    }
  }
}

• El estado y el agente actuales van en conversation, y los anteriores en
  change. Compare los dos para saber qué cambió.
• actor dice quién hizo el cambio:

Solo llega cuando el estado o el agente cambian de verdad: volver a cerrar una conversación
ya cerrada no dispara nada. En cuentas con chatbots activos puede ser un evento frecuente.

Límites de Meta

• Solo se le puede escribir a quien ya le escribió a la página.
• Pasadas 24 horas desde el último mensaje del cliente, la ventana se cierra y no se le
  puede responder hasta que vuelva a escribir. window_expires_at indica cuándo.
• No hay plantillas ni conversaciones iniciadas por la empresa.

Qué nunca viaja

Ni la foto de perfil (Meta la firma y la URL vence en días), ni identificadores internos de
Wasapi que no sirvan para consultar la API, ni las notas internas del historial de la
conversación.

Ver también

• Introducción — configuración, entrega y reintentos
• Eventos de encuesta — las encuestas de Instagram y
  Messenger traen channel_type y channel_uuid