Plataforma de Messenger

Webhooks de Meta para la plataforma de Messenger

Los webhooks de Meta te permiten recibir en tiempo real notificaciones HTTP sobre cambios en objetos específicos en la gráfica social de Meta. Por ejemplo, podemos enviarte una notificación cuando una persona envía un mensaje a tu página de Facebook o a tu cuenta profesional de Instagram. Las notificaciones de webhooks te permiten hacer seguimiento de los mensajes de entrada y de las actualizaciones de estado del mensaje. Además, te permiten evitar los límites de frecuencia que podrían producirse si enviaras consultas a los puntos de conexión de la plataforma de Messenger para hacer seguimiento de estos cambios.

A fin de implementar con éxito webhooks en las conversaciones en Messenger o Instagram, deberás hacer lo siguiente:

  1. Crear un punto de conexión en tu servidor para recibir y procesar tus notificaciones de webhooks y objetos JSON.
  2. Configurar el producto Webhooks de Meta en el panel de tu app.
  3. Suscribirte a las notificaciones de webhooks de Meta que deseas recibir.
  4. Instalar la app de mensajes en la página de Facebook vinculada a tu cuenta comercial o tu cuenta profesional de Instagram.

Antes de empezar

Suponemos que, antes de empezar, hiciste lo siguiente:

Configurar el servidor Node.js.

El servidor de conexión debe tener la capacidad de procesar dos tipos de solicitudes HTTPS: solicitudes de verificación y notificaciones de eventos. Como ambas solicitudes utilizan HTTP, el servidor debe contar con un certificado TLS o SSL válido, correctamente configurado e instalado. No se admiten certificados autofirmados.

En las secciones que figuran a continuación, se explica qué incluye cada tipo de solicitud y cómo responder a cada una de ellas.

Los ejemplos de código que se muestran aquí se tomaron de nuestra app de ejemplo, que está alojada en GitHub . Visita GitHub para ver el ejemplo completo y obtener más información sobre cómo configurar tu servidor de webhooks.

Crear un punto de conexión

Cuando creas un punto de conexión para recibir notificaciones de webhooks desde la plataforma de Messenger, es posible que el archivo app.js tenga el siguiente aspecto:

// Create the endpoint for your webhook

app.post("/webhook", (req, res) => {
  let body = req.body;

  console.log(`\u{1F7EA} Received webhook:`);
  console.dir(body, { depth: null });
    
...

Este código crea un punto de conexión /webhook que acepta solicitudes POST y verifica que estas sean notificaciones de webhooks.

Devolución de una respuesta 200 OK

El punto de conexión debe devolver una respuesta 200 OK, que le indica a la plataforma de Messenger que el evento se recibió y no se debe volver a enviar. Normalmente, no enviarás esta respuesta hasta que hayas completado el procesamiento de la notificación.

Responder a notificaciones de eventos

Tu punto de conexión debe responder a todas las notificaciones:

  • con una respuesta 200 OK HTTPS;
  • dentro de un plazo de cinco o menos segundos.

El siguiente código estará en la app.post del archivo app.js y es probable que tenga el siguiente aspecto:

...
  // Send a 200 OK response if this is a page webhook

  if (body.object === "page") {
    // Returns a '200 OK' response to all requests
    res.status(200).send("EVENT_RECEIVED");
...
    // Determine which webhooks were triggered and get sender PSIDs and locale, message content and more.
...
  } else {
    // Return a '404 Not Found' if event is not from a page subscription
    res.sendStatus(404);
  }
});

Solicitudes de verificación

Siempre que configures el producto Webhooks en el panel de apps, enviaremos una solicitud GET a la URL del punto de conexión. Las solicitudes de verificación incluyen los siguientes parámetros de cadenas de consulta, como anexos al final de la URL del punto de conexión. Se verán similares a lo siguiente:

Ejemplo de solicitud de verificación

GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.verify_token=mytoken& hub.challenge=1158201444

Validación de solicitudes de verificación

Cada vez que el punto de conexión recibe una solicitud de verificación, debe hacer lo siguiente:

  • Verificar que el valor de hub.verify_token coincida con la cadena configurada en el campo Token de verificación al configurar el producto Webhooks en el panel de tu app (aún no configuraste esta cadena de token).
  • Responder con el valor hub.challenge.

El archivo app.js puede tener el siguiente aspecto:

// Add support for GET requests to our webhook
app.get("/messaging-webhook", (req, res) => {
  
// Parse the query params
  let mode = req.query["hub.mode"];
  let token = req.query["hub.verify_token"];
  let challenge = req.query["hub.challenge"];

  // Check if a token and mode is in the query string of the request
  if (mode && token) {
    // Check the mode and token sent is correct
    if (mode === "subscribe" && token === config.verifyToken) {
      // Respond with the challenge token from the request
      console.log("WEBHOOK_VERIFIED");
      res.status(200).send(challenge);
    } else {
      // Respond with '403 Forbidden' if verify tokens do not match
      res.sendStatus(403);
    }
  }
});
ParámetroValor de ejemploDescripción

hub.mode

subscribe

Este valor siempre estará configurado como subscribe.

hub.challenge

1158201444

Un int que debes volver a transmitirnos.

hub.verify_token

mytoken

Una cadena que tomamos del campo Token de verificación en el panel de apps de tu app. Configurarás esta cadena cuando completes los pasos de los parámetros de configuración de Webhooks.

Nota: PHP convierte los puntos (.) en guiones bajos (_) de los nombres de parámetros .

Si estás en tu panel de apps y configuras el producto Webhooks (y, por lo tanto, activas una solicitud de verificación), el panel indicará si el punto de conexión validó correctamente la solicitud. Si utilizas el punto de conexión /app/subscriptions de la API Graph para configurar el producto Webhooks, la API indicará si la operación se realizó correctamente o no.

Notificaciones de eventos

Cuando configures tu producto Webhooks, te suscribirás a campos (fields) específicos en un tipo de objeto (object) (p. ej., el campo messages en el objeto page). Siempre que haya un cambio en uno de esos campos, enviaremos a tu punto de conexión una solicitud POST con una carga JSON que describe el cambio.

Por ejemplo, si te suscribiste al campo page del objeto message_reactions y uno de los usuarios reaccionó a un mensaje enviado por tu app, te enviaremos una solicitud POST que se vería así:

{
  "object":"page",
  "entry":[
    {
      "id":"<PAGE_ID>",
      "time":1458692752478,
      "messaging":[
        {
          "sender":{
            "id":"<PSID>"
          },
          "recipient":{
            "id":"<PAGE_ID>"
          },

          ...
        }
      ]
    }
  ]
}

Contenido de la carga

Las cargas incluirán un objeto que describirá el cambio. Al configurar el producto Webhooks, puedes indicar si las cargas solo deben incluir los nombres de los campos modificados o si deben incluir también los nuevos valores.

Damos formato JSON a todas las cargas para que puedas analizarlas con paquetes o métodos de análisis JSON comunes.

No almacenamos los datos de notificaciones de eventos de webhook que te enviamos. Por lo tanto, debes asegurarte de capturar y almacenar todo el contenido de carga que quieras conservar.

Validar cargas

Firmamos todas las cargas de la notificación de eventos con una firma SHA256 e incluimos la firma en el encabezado "X-Hub-Signature-256" de la solicitud, precedido por "sha256=". No es necesario que valides la carga, pero te lo recomendamos encarecidamente.

Para validar la carga:

  1. Genera una firma SHA256 con la carga y con la clave secreta de la app.
  2. Compara tu firma con la del encabezado X-Hub-Signature-256 (todo lo que aparece después de sha256=). Si las firmas coinciden, la carga es genuina.

Ten en cuenta que generamos la firma usando una versión unicode con escape de la carga, con dígitos hexadecimales en minúsculas. Si solamente realizas el cálculo en relación con los bytes descodificados, obtendrás una firma diferente. Por ejemplo, la cadena äöå se debe escribir de la siguiente manera: \u00e4\u00f6\u00e5.

El archivo app.js puede tener el siguiente aspecto:

// Import dependencies and set up http server
const express = require("express"),
  bodyParser = require("body-parser"),
  { urlencoded, json } = require("body-parser"),
  app = express().use(bodyParser.json());
    
    ...


// Verify that the callback came from Facebook.
function verifyRequestSignature(req, res, buf) {
  var signature = req.headers["x-hub-signature-256"];

  if (!signature) {
    console.warn(`Couldn't find "x-hub-signature-256" in headers.`);
  } else {
    var elements = signature.split("=");
    var signatureHash = elements[1];
    var expectedHash = crypto
      .createHmac("sha256", config.appSecret)
      .update(buf)
      .digest("hex");
    if (signatureHash != expectedHash) {
      throw new Error("Couldn't validate the request signature.");
    }
  }
}

Reintento de entrega de webhooks

Si se produce un error al enviar una notificación a tu servidor, volveremos a intentar enviarla varias veces más. Tu servidor deberá manejar la deduplicación en esos casos. Si 15 minutos después seguimos sin poder entregar las notificaciones, se enviará una alerta a tu cuenta de desarrollador.

Si el error en la entrega de la notificación persiste durante una hora, recibirás una alerta de webhooks inhabilitados y tu app se dará de baja del webhook de la página o de la cuenta profesional de Instagram. Una vez que hayas solucionado los problemas, deberás volver a realizar la suscripción a los webhooks.

Prueba tus webhooks

Para probar tu verificación de webhooks, ejecuta la siguiente solicitud cURL con tu token de verificación:

curl -X GET "localhost:1337/webhook?hub.verify_token=YOUR-VERIFY-TOKEN&hub.challenge=CHALLENGE_ACCEPTED&hub.mode=subscribe"

Si la verificación del webhook funciona según lo previsto, este es el aspecto que debe tener:

  • WEBHOOK_VERIFIED registrado en la línea de comandos en la que se ejecuta el proceso del nodo.
  • CHALLENGE_ACCEPTED registrado en la línea de comandos a la que enviaste la solicitud cURL.

Para probar tu webhook, envía esta solicitud cURL:

curl -H "Content-Type: application/json" -X POST "localhost:1337/webhook" -d '{"object": "page", "entry": [{"messaging": [{"message": "TEST_MESSAGE"}]}]}'

Si el webhook funciona según lo previsto, este es el aspecto que debe tener:

  • TEST_MESSAGE registrado en la línea de comandos en la que se ejecuta el proceso del nodo.
  • EVENT RECEIVED registrado en la línea de comandos a la que enviaste la solicitud cURL.

Suscribirse a Webhooks de Meta

Una vez que el punto de conexión del servidor de webhook o la app de ejemplo estén listos, ve al panel de apps de tu app y suscríbete a Webhooks de Meta.

En este ejemplo, usaremos el panel para configurar un webhook y hacer la suscripción al campo messages. Cada vez que un cliente envíe un mensaje a tu app, se enviará una notificación a tu punto de conexión de webhook.

  1. En el panel de apps, ve a Productos > Messenger > Configuración.
    • Algunos webhooks de la plataforma de Messenger no están disponibles para los mensajes de Instagram. Si solo deseas implementar webhooks para Instagram y conoces los que están disponibles para los mensajes de Instagram, puedes suscribirte aquí a los webhooks. Si solo deseas ver y suscribirte a los webhooks para los mensajes de Instagram, puedes ir a la configuración de Instagram.

  2. Ingresa la URL de tu punto de conexión en el campo URL de devolución de llamada y agrega el token de verificación en el campo Token de verificación. Incluiremos esta cadena en todas las solicitudes de verificación. Si usas alguna de nuestras apps de ejemplo, debe ser la misma cadena que usaste para la variable de configuración TOKEN.

  3. Suscríbete a los campos respecto de los que te gustaría recibir notificaciones y haz clic en Guardar.

  4. El último paso consiste en suscribirse a campos individuales. Suscríbete al campo messages y envía una notificación de evento de prueba.

    Si el punto de conexión está configurado correctamente, debería validar la carga útil y ejecutar el código que hayas configurado para que se ejecute después de una validación exitosa. Si usas nuestra app de ejemplo, carga la URL de la app en el navegador web. Debería mostrar el contenido de la carga.

Puedes cambiar tus suscripciones de webhooks, el token de verificación o la versión de la API en cualquier momento desde el panel de apps.

Nota: Te recomendamos usar la versión más reciente de la API para recibir toda la información disponible de los webhooks.

También puedes hacer esto de manera programática mediante el punto de conexión /app/subscriptions.

Campos disponibles en la plataforma de Messenger

Evento de webhookDescripción

messages

Suscribe a los eventos de mensaje recibido.

messaging_account_linking

Suscribe a los eventos de vinculación de cuentas.

messaging_checkout_updates (beta)

Suscribe a los eventos de pago actualizado.

message_deliveries

Suscribe a los eventos de mensaje entregado.

message_echoes

Suscribe a los eventos de mensaje eco.

messaging_game_plays

Suscribe a los eventos de juego instantáneo

messaging_handovers (beta)

Suscribe a los eventos de protocolo "Handover"

messaging_optins

Suscribe a los eventos de aceptación del plugin.

messaging_payments (beta)

Suscribe a los eventos de pago.

messaging_policy_enforcement

Suscribe a los eventos de aplicación de políticas

messaging_postbacks

Suscribe a los eventos recibidos de postback.

messaging_pre_checkouts (beta)

Suscribe a los eventos previos al pago

message_reads

Suscribe a los eventos de mensaje leído.

messaging_referrals

Suscribe a los eventos de referencia.

standby (beta)

Suscribe a los eventos del canal en espera del protocolo "Handover"

Conexión de tu app

Deberás conectar tu app de Webhooks a tu página y suscribir esta última a las notificaciones de webhooks que desees recibir.

Agregar la app

Puedes conectar una app a una página enMeta Business Suite > Todas las herramientas > Apps de negocio

Nota: Deberás suscribir todas las apps de mensajes de tu empresa a los webhooks de mensajes.

Suscribir tu página

Deberás suscribir tu página a las notificaciones de webhooks que desees recibir.

Requisitos

Para suscribirte a un campo de webhooks, envía una solicitud POST al perímetro subscribed_apps de la página usando el token de acceso a esta.

curl -i -X POST "https://graph.facebook.com/PAGE-ID/subscribed_apps
  ?subscribed_fields=messages
  &access_token=PAGE-ACCESS-TOKEN"

Ejemplo de respuesta

{
  "success": "true"
}

Para ver las apps instaladas en tu página, envía una solicitud GET:

Ejemplo de solicitud

curl -i -X GET "https://graph.facebook.com/PAGE-ID/subscribed_apps
  &access_token=PAGE-ACCESS-TOKEN"

Ejemplo de respuesta

{
  "data": [
    {
      "category": "Business",
      "link": "https://my-clever-domain-name.com/app",
      "name": "My Sample App",
      "id": "APP-ID"
      "subscribed_fields": [
        "messages"
      ]
    }
  ]
}

Si no hay apps instaladas en tu página, la API devolverá un conjunto de datos vacío.

Explorador de la API Graph

También puedes usar el explorador de la API Graph para enviar la solicitud de suscripción a tu página a un campo de Webhooks.

  1. Selecciona tu app en el menú desplegable App.
  2. Haz clic en el menú desplegable Obtener token y selecciona Obtener token de acceso de usuario, y luego elige el permiso pages_manage_metadata. Esto cambiará el token de tu app por un token de acceso de usuario con el permiso pages_manage_metadata otorgado.
  3. Vuelve a hacer clic en Obtener token y selecciona tu página. Esto cambiará tu token de acceso de usuario por un token de acceso a la página.
  4. Cambia el modo de operación haciendo clic en el menú desplegable GET y seleccionando POST.
  5. Reemplaza la consulta predeterminada me?fields=id,name por el identificador de la página seguido por /subscribed_apps y, luego, envía la consulta.

Requisitos de acceso

La app solo necesita acceso estándar para recibir notificaciones de personas que tienen un rol en tu app como administradores, desarrolladores o evaluadores. En cambio, para recibir notificaciones de clientes o personas que no tienen un rol en tu app, esta necesita acceso avanzado.

Obtén más información sobre el acceso estándar y el acceso avanzado , los datos a los que puedes acceder con cada uno y los requisitos de implementación.

Próximos pasos

  • Envía un mensaje de prueba: obtén información sobre cómo usar la plataforma para enviar un mensaje.
  • Conoce nuestra app de muestra : descarga el código de nuestra app de muestra para obtener más información sobre las funciones que ofrece la plataforma de Messenger.

    • Más información