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:
Suponemos que, antes de empezar, hiciste lo siguiente:
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.
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.
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.
Tu punto de conexión debe responder a todas las notificaciones:
200 OK HTTPS
;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); } });
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:
GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.verify_token=mytoken& hub.challenge=1158201444
Cada vez que el punto de conexión recibe una solicitud de verificación, debe hacer lo siguiente:
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).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ámetro | Valor de ejemplo | Descripción |
---|---|---|
|
| Este valor siempre estará configurado como |
|
| Un |
|
| 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.
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>"
},
...
}
]
}
]
}
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.
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:
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."); } } }
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.
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.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.
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
.
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
.
Evento de webhook | Descripción |
---|---|
| Suscribe a los eventos de mensaje recibido. |
| Suscribe a los eventos de vinculación de cuentas. |
| Suscribe a los eventos de pago actualizado. |
| Suscribe a los eventos de mensaje entregado. |
| Suscribe a los eventos de mensaje eco. |
| Suscribe a los eventos de juego instantáneo |
| Suscribe a los eventos de protocolo "Handover" |
| Suscribe a los eventos de aceptación del plugin. |
| Suscribe a los eventos de pago. |
| Suscribe a los eventos de aplicación de políticas |
| Suscribe a los eventos recibidos de postback. |
| Suscribe a los eventos previos al pago |
| Suscribe a los eventos de mensaje leído. |
| Suscribe a los eventos de referencia. |
| Suscribe a los eventos del canal en espera del protocolo "Handover" |
Deberás conectar tu app de Webhooks a tu página y suscribir esta última a las notificaciones de webhooks que desees recibir.
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.
Deberás suscribir tu página a las notificaciones de webhooks que desees recibir.
MODERATE
en la página que se está consultando
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 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"
{ "success": "true" }
Para ver las apps instaladas en tu página, envía una solicitud GET
:
curl -i -X GET "https://graph.facebook.com/PAGE-ID/subscribed_apps &access_token=PAGE-ACCESS-TOKEN"
{ "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.
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.
pages_manage_metadata
. Esto cambiará el token de tu app por un token de acceso de usuario con el permiso pages_manage_metadata
otorgado.GET
y seleccionando POST
.me?fields=id,name
por el identificador de la página seguido por /subscribed_apps
y, luego, envía la consulta. 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.