Webhooks

Las cuentas de WhatsApp Business (WABA) y sus activos son objetos de la gráfica social de Facebook. Cuando se produce un evento que activa uno de esos objetos, Facebook lo ve y envía una notificación a la URL del webhook especificada en el panel de la aplicación de Facebook.

En el contexto del registro insertado, puedes usar webhooks para recibir notificaciones de cambios que se realicen en tus cuentas WABA, números de teléfono, plantillas de mensajes y mensajes enviados a tus números de teléfono.

Debes suscribirte individualmente a cada cuenta WABA para la que quieras recibir webhooks. Después de recuperar el identificador de la cuenta WABA del cliente, suscribe la aplicación al identificador para empezar a recibir webhooks.

Consulta Webhooks para cuentas de WhatsApp Business para obtener más información sobre la suscripción a Webhooks.

Suscribirse a una cuenta de WhatsApp Business

En primer lugar, configura el producto Webhooks para la aplicación:

1. Carga la aplicación en el panel de aplicaciones y añade el producto Webhooks si todavía no lo has añadido.
2. Haz clic en el producto Webhooks en el menú de la izquierda.
3. Selecciona Cuenta de WhatsApp Business en el menú desplegable y, a continuación, haz clic en Suscribirse a este objeto.
4. Añade la URL de devolución de llamada de webhooks y el identificador de verificación, verifica la información y guarda los cambios.

Para obtener más información sobre la suscripción a Webhooks en el panel de aplicaciones, consulta Configurar el producto Webhooks.

Una vez configurados los webhooks en la ventana del producto Webhooks, envía una solicitud POST al extremo subscribed_apps de la cuenta de WhatsApp Business para la que quieras recibir webhooks.

Incluye el identificador de acceso de usuario del sistema en el encabezado de la solicitud con el prefijo Authorization: Bearer. Si necesitas ayuda para generar tu identificador de acceso de usuario del sistema, consulta Usuarios del sistema, Instalar aplicaciones y generar identificadores.

Sintaxis de la solicitud

POST https://graph.facebook.com/<API_VERSION>/<WABA_ID>/subscribed_apps

Ejemplo de solicitud

curl -X POST \
'https://graph.facebook.com/v19.0/102289599326934/subscribed_apps' \
-H 'Authorization: Bearer EAAJi...'

Ejemplo de respuesta

{
   "success" : true
}

Tu aplicación (identificada mediante el identificador de acceso de usuario del sistema) ya debería recibir notificaciones de webhooks que describan los cambios realizados en la cuenta de WhatsApp Business.

Repite este proceso con las demás cuentas WABA para las que quieras recibir notificaciones de webhooks. Ten en cuenta que, si suscribes la aplicación a webhooks para varias cuentas WABA, todas las notificaciones de webhooks se enviarán a la URL de devolución de llamada de la aplicación especificada en la ventana del producto Webhooks del panel de aplicaciones.

Si quieres usar URL de devolución de llamada diferentes para cada cuenta WABA, debes crear aplicaciones independientes (cada una con su propia URL de devolución de llamada) para cada cuenta WABA y realizar la solicitud anterior en cada cuenta WABA con el identificador de acceso de usuario del sistema de cada aplicación. Como alternativa, si quieres usar una sola aplicación, puedes anular la URL de devolución de llamada al suscribirte a webhooks para cada cuenta WABA. Consulta Anular la URL de devolución de llamada.

Obtener una lista de todas las suscripciones de una cuenta de WhatsApp Business

A fin de obtener una lista de las aplicaciones suscritas a webhooks para una cuenta WABA, envía una solicitud GET al extremo subscribed_apps de la cuenta WABA:

Sintaxis de la solicitud

GET https://graph.facebook.com/<API_VERSION>/<WABA_ID>/subscribed_apps

En una respuesta correcta, se incluye una matriz de aplicaciones que se han suscrito a la cuenta WABA, con las propiedades link, name e id de cada una de ellas.

Ejemplo de solicitud

curl \
'https://graph.facebook.com/v19.0/102289599326934/subscribed_apps' \
-H 'Authorization: Bearer EAAJi...'

Ejemplo de respuesta

{
  "data" : [
    {
      "whatsapp_business_api_data" : {
        "id" : "67084...",
        "link" : "https://www.facebook.com/games/?app_id=67084...",
        "name" : "Jaspers Market"
      }
    },
    {
      "whatsapp_business_api_data" : {
        "id" : "52565...",
        "link" : "https://www.facebook.com/games/?app_id=52565...",
        "name" : "Jaspers Fresh Finds"
      }
    }
  ]
}

Cancelar la suscripción de una cuenta WABA

A fin de cancelar la suscripción de tu aplicación a webhooks para una cuenta de WhatsApp Business, envía una solicitud DELETE al extremo subscribed_apps de la cuenta WABA.

Sintaxis de la solicitud

DELETE https://graph.facebook.com/<API_VERSION>/<WABA_ID>/subscribed_apps

Ejemplo de solicitud

curl -X DELETE \
'https://graph.facebook.com/v19.0/102289599326934/subscribed_apps' \
-H 'Authorization: Bearer EAAJi...'

Ejemplo de respuesta

{
   "success" : true
}

Anular la URL de devolución de llamada

Consulta Anulaciones de webhooks.

Configurar notificaciones

Puedes configurar webhooks para recibir notificaciones de cambios en las cuentas de WhatsApp Business que hayas suscrito. Puedes suscribirte a los tipos de notificaciones siguientes:

Campos de suscripción disponibles

Para obtener más información, consulta la documentación de Webhooks para cuentas de WhatsApp Business.

Formato de webhooks

Recibes notificaciones en el siguiente formato general:

{
  "object": "whatsapp_business_account",
  "entry": [
    { // entry object, containing changes
      "changes": [
        { // changes object, containing value
          "value": {
            // value object
          }
        }
      ]
    }
  ]
}

Consulta más detalles acerca de cada campo:

• object
• entry
• changes
• value

Ejemplos

Actualizaciones del número de teléfono

Actualización del nombre recibida

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "waba-id",
      "time": 1608243053,
      "changes": [
        {
          "field": "phone_number_name_update",
          "value": {
            "display_phone_number": "16505551111",
            "decision": "APPROVED",
            "requested_verified_name": "WhatsApp",
            "rejection_reason": null
          }
        }
      ]
    }
  ]
}

Actualización de calidad recibida

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "waba-id",
      "time": 1608243062,
      "changes": [
        {
          "field": "phone_number_quality_update",
          "value": {
            "display_phone_number": "16505551111",
            "event": "FLAGGED",
            "current_limit": "TIER_10K"
          }
        }
      ]
    }
  ]
}

Actualizaciones de la cuenta WABA

Actualización de número de espacio aislado a cuenta verificada

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703058,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "phone_number": "16505551111",
            "event": "VERIFIED_ACCOUNT"
          }
        }
      ]
    }
  ]
}

Cuenta de WhatsApp Business bloqueada

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703058,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "DISABLED_UPDATE"
            "ban_info": {
              "waba_ban_state": ["SCHEDULE_FOR_DISABLE", "DISABLE", "REINSTATE"],
              "waba_ban_date": "January 31, 2021"
            }
          }
        }
      ]
    }
  ]
}

Revisión de cuenta de WhatsApp Business completada

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703141,
      "changes": [
        {
          "field": "account_review_update",
          "value": {
            "decision": "APPROVED"
          }
        }
      ]
    }
  ]
}

Actualizaciones de la plantilla de mensajes

Aprobado

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703141,
      "changes": [
        {
          "field": "message_template_status_update",
          "value": { 
              "event": "APPROVED",
              "message_template_id": 1234567, 
              "message_template_name": "My message template",
              "message_template_language": "en-US",
              "reason": null 
         }
       }
      ]
    }
  ]
}