Webhooks de Meta para la plataforma de Messenger

Gracias a los webhooks de Meta, podrás recibir notificaciones HTTP en tiempo real sobre los cambios que se produzcan en determinados objetos de la gráfica social de Meta. Por ejemplo, te podemos enviar una notificación cuando un usuario envíe un mensaje a tu página de Facebook o a tu cuenta profesional de Instagram. Las notificaciones de webhooks te permiten hacer un seguimiento de los mensajes entrantes y de las actualizaciones de estado de los mensajes. Gracias a las notificaciones de los webhooks, también puedes evitar los límites de frecuencia que se podrían producir si consultas los extremos de la plataforma de Messenger para hacer un seguimiento de estos cambios.

A fin de implementar los webhooks para las conversaciones de Messenger o Instagram correctamente, necesitarás hacer lo siguiente:

1. Crear un extremo en el servidor para recibir y procesar las notificaciones de los webhooks, objetos JSON.
2. Configurar el producto Webhooks de Meta en el panel de aplicaciones.
3. Suscribirte a las notificaciones de Webhooks de Meta que quieras recibir.
4. Descargar tu aplicación de mensajes en la página de Facebook vinculada a la empresa o la cuenta profesional de Instagram.

Antes de empezar

Antes de empezar, suponemos que has hecho lo siguiente:

• Leído e implementado los componentes necesarios para desarrollar con Meta en la Información general de la plataforma de Messenger .

Configurar el servidor Node.js

El servidor debe ser capaz de procesar dos tipos de solicitudes HTTPS: solicitudes de verificación y notificaciones de eventos. Dado que ambas solicitudes usan HTTPS, el servidor debe tener un certificado TLS o SSL válido configurado e instalado correctamente. Ten en cuenta que no se admiten los certificados autofirmados.

En las secciones incluidas a continuación se explica qué habrá en cada tipo de solicitud y cómo responder a ellas.

Los ejemplos de código que se muestran aquí se han extraído de nuestra aplicación de ejemplo ubicada en GitHub . Visita GitHub para ver el ejemplo completo y obtener más información sobre la configuración del servidor de webhooks.

Crear un extremo

Para crear un extremo en el que recibir notificaciones de webhooks de la plataforma de Messenger, el archivo app.js podría tener un aspecto similar al siguiente:

// 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 extremo /webhook que acepta solicitudes POST y comprueba si la solicitud es una notificación de webhook.

Devolver una respuesta 200 OK

El extremo debe devolver una respuesta 200 OK, que indica a la plataforma de Messenger que el evento se ha recibido y que no es necesario volver a enviarlo. Por lo general, no enviarás esta respuesta hasta que hayas terminado de procesar la notificación.

Responder a notificaciones de eventos

El extremo debe responder a todas las notificaciones:

• con una respuesta 200 OK HTTPS
• en cinco segundos o menos

El siguiente código estará en app.post en el archivo app.js y podría tener un aspecto similar al siguiente:

...
  // 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

Al configurar el producto Webhooks en el panel de aplicaciones, enviaremos una solicitud GET a la URL del extremo. En las solicitudes de verificación se incluyen los siguientes parámetros de cadena de consulta, anexados al final de la URL del extremo. El aspecto será similar al 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

Validar solicitudes de verificación

Cada vez que el extremo recibe una solicitud de verificación, debe realizar las acciones siguientes:

• Verificar que el valor de hub.verify_token coincide con la cadena establecida en el campo Identificador de verificación al configurar el producto Webhooks en el panel de aplicaciones (esta cadena de identificador no se ha configurado todavía).
• Responder con el valor de hub.challenge.

El archivo app.js podría tener un aspecto similar al siguiente:

// 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);
    }
  }
});

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

Si estás en el panel de aplicaciones configurando el producto Webhooks (y, por lo tanto, activando una solicitud de verificación), el panel indicará si el extremo ha validado correctamente la solicitud. Si usas el extremo /app/subscriptions de la API Graph para configurar el producto Webhooks, la API indicará en la respuesta si la operación se ha realizado correctamente o no.

Notificaciones de eventos

Al configurar el producto Webhooks, te suscribirás a campos (fields) específicos de un tipo de objeto (object); p. ej., el campo messages del objeto page. Cuando se produce un cambio en uno de estos campos, enviaremos una solicitud POST al extremo con una carga útil JSON que describirá el cambio.

Por ejemplo, si te has suscrito al campo message_reactions del objeto page y un usuario ha reaccionado a un mensaje que ha enviado tu aplicación, te enviaremos una solicitud POST que tendrá un aspecto similar al siguiente:

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

          ...
        }
      ]
    }
  ]
}

Contenido de la carga útil

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

Damos formato a todas las cargas útiles mediante JSON, por lo que puedes analizarlas mediante los paquetes o métodos comunes de análisis de JSON.

Validar cargas útiles

Firmamos todas las cargas útiles de notificación de eventos con una firma SHA256 e incluimos la firma en el encabezado "X-Hub-Signature-256" de la solicitud precedida por "sha256=". No tienes que validar la carga útil, pero te lo recomendamos encarecidamente.

Para validar la carga útil, sigue estos pasos:

1. Genera una firma SHA256 mediante la carga útil y la clave secreta de la aplicación.
2. Compara tu firma con la del encabezado X-Hub-Signature-256 (todo lo que haya después de sha256=). Si las firmas coinciden, la carga útil es auténtica.

El archivo app.js podría tener un aspecto similar al siguiente:

// 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 en una notificación enviada a tu servidor, lo intentaremos varias veces más, con carácter inmediato. En estos casos, el servidor debe administrar la eliminación de duplicados. Si, pasados 15 minutos, seguimos sin poder entregar notificaciones, se enviará una alerta a tu cuenta de desarrollador.

Si la notificación sigue sin poderse entregar durante 1 hora, recibirás una alerta de webhooks desactivados y se eliminará la suscripción de tu aplicación a webhooks de la página o de la cuenta profesional de Instagram. Una vez que hayas corregido los problemas, tendrás que volver a suscribirte a los webhooks.

Probar los webhooks

Para probar la verificación del webhook, ejecuta la siguiente solicitud de cURL con tu identificador 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, deberías comprobar lo siguiente:

• El elemento WEBHOOK_VERIFIED registrado en la línea de comandos en la que se ejecuta el proceso del nodo.
• El elemento CHALLENGE_ACCEPTED registrado en la línea de comandos en la que has enviado la solicitud cURL.

Para probar el webhook, envía la siguiente solicitud de 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, deberías ver lo siguiente:

• El elemento TEST_MESSAGE registrado en la línea de comandos en la que se ejecuta el proceso del nodo.
• El elemento EVENT RECEIVED registrado en la línea de comandos donde has enviado la solicitud cURL.

Suscribirse a los webhooks de Meta

Cuando la aplicación de ejemplo o el extremo del servidor de los webhooks esté listo, ve al panel de aplicaciones de tu aplicación para suscribirte a los webhooks de Meta.

En este ejemplo, utilizaremos el panel para configurar un webhook y suscribirnos al campo messages. Cuando un cliente envíe un mensaje a tu aplicación, se enviará una notificación al extremo de webhooks.

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

2. Introduce la URL del extremo en el campo URL de devolución de llamada y añade el identificador de verificación al campo Identificador de verificación. Esta cadena se incluirá en todas las solicitudes de verificación. Si utilizas una de nuestras aplicaciones de ejemplo, esta cadena debe ser la misma que la utilizada para la variable de configuración TOKEN de tu aplicación.

3. Suscríbete a los campos para los que quieras 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 extremo está configurado correctamente, debe validar la carga útil y ejecutar el código que hayas configurado para ejecutarse cuando se realice correctamente una validación. Si utilizas nuestra aplicación de ejemplo, carga la URL de la aplicación en el navegador web. Debe mostrar el contenido de la carga útil.

Puedes cambiar la suscripción a los webhooks, el identificador de verificación o la versión de la API en cualquier momento mediante el panel de aplicaciones.

Nota: Te recomendamos que uses la versión más reciente de la API para recibir toda la información disponible para cada webhook.

Si quieres hacerlo mediante programación, utiliza el extremo /app/subscriptions.

Campos disponibles de la plataforma de Messenger

Conectar la aplicación

Deberás conectar la aplicación Webhooks a tu página y suscribirla a las notificaciones de los webhooks que quieras recibir.

Añadir la aplicación

Puedes conectar una aplicación a una página en Meta Business Suite > Todas las herramientas > Aplicaciones empresariales .

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

Suscribir la página

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

Requisitos

• Un identificador de acceso a la página solicitado por una persona que pueda realizar la tarea MODERATE en la página que se consultará.
• Los permisos pages_messaging y pages_manage_metadata.

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

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 saber qué aplicaciones ha descargado la página, envía una solicitud GET en su lugar:

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 la página no ha descargado ninguna aplicación, 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 a fin de suscribir la página a un campo de webhooks.

1. Selecciona tu aplicación en el menú desplegable Aplicación.
2. Haz clic en el menú desplegable Obtener identificador y selecciona Obtener identificador de acceso de usuario. Después, elige el permiso pages_manage_metadata. De este modo, el identificador de la aplicación se cambiará por un identificador de acceso de usuario que tenga concedido el permiso pages_manage_metadata.
3. Haz clic en Obtener identificador nuevamente y selecciona tu página. De este modo, el identificador de acceso de usuario se cambiará por un identificador de acceso a la página.
4. Para cambiar el método de operación, haz clic en el menú desplegable GET y selecciona POST.
5. Reemplaza la consulta me?fields=id,name predeterminada por el identificador de la página seguido del elemento /subscribed_apps y, después, envía la consulta.

Requisitos de acceso

Para recibir notificaciones de usuarios que tengan un rol en la aplicación, como los administradores, los desarrolladores o los evaluadores, la aplicación solo necesita acceso estándar. Para que los usuarios que no tengan ningún rol en la aplicación reciban notificaciones de los clientes, la aplicación necesitará 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 la implementación.

Siguientes pasos

Introducción a nuestra aplicación de ejemplo: descarga el código de nuestra aplicación de ejemplo para obtener más información sobre las funciones que puede ofrecer la plataforma de Messenger.

Más información

• Obtén más información sobre cómo recibir notificaciones cuando se pase una conversación desde una aplicación a otra mediante el protocolo de traspaso de Messenger.
• Obtén más información sobre los webhooks de Meta para la API Graph.