Administrar webhooks

Las cuentas de WhatsApp Business (WABA) y sus activos son objetos de la gráfica social de Facebook. Facebook nota cuando se produce un evento de activación de uno de esos objetos y envía una notificación a la URL del webhook especificada en tu panel de la app de Facebook.

En relación con el registro incrustado, puedes usar webhooks para recibir notificaciones relativas a cambios en tus WABA, números de teléfono, plantillas de mensajes y mensajes enviados a tus números de teléfono.

Debes suscribirte por separado a cada WABA en la que quieras recibir webhooks. Después de obtener el identificador de la WABA del cliente, suscribe tu app al identificador para empezar a recibir webhooks.

Consulta Webhooks para cuentas de WhatsApp Business si quieres 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 tu app:

1. Carga tu app en el panel de la app y agrega el producto Webhooks si aún no lo hiciste.
2. En el menú que está ubicado a la izquierda, haz clic en el producto Webhooks.
3. En el menú desplegable, selecciona Cuenta de WhatsApp Business y, luego, haz clic en Suscribirte a este objeto.
4. Agrega la URL de devolución de llamada de Webhooks y el token de verificación y verifica y guarda tus cambios.

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

Una vez que hayas configurado los webhooks en el panel de productos Webhooks, envía una solicitud POST al punto de conexión subscribed_apps de la cuenta de WhatsApp Business en la que deseas recibir webhooks.

Incluye el token de acceso de usuario del sistema en el encabezado de la solicitud, anteponiendo Authorization: Bearer. Si quieres obtener ayuda para generar tu token de acceso de usuario del sistema, consulta Usuarios del sistema, instalar apps y generar tokens.

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/v21.0/102289599326934/subscribed_apps' \
-H 'Authorization: Bearer EAAJi...'

Ejemplo de respuesta

{
   "success" : true
}

Tu app (identificada por el token de acceso de usuario del sistema) debería recibir ahora notificaciones de webhook que describan los cambios en la cuenta de WhatsApp Business.

Repite este proceso para cualquier otra WABA en la que desees recibir notificaciones de webhook. Ten en cuenta que, si suscribes tu app a los webhooks para múltiples WABA, todas las notificaciones de webhook se enviarán a la URL de devolución de llamada de la app especificada en el panel de producto Webhooks ubicado en el panel de apps.

Si deseas usar diferentes URL de devolución de llamada para cada WABA, debes crear apps separadas, donde cada una tenga su propia URL de devolución de llamada, para cada WABA y realizar la consulta anterior en relación con cada WABA mediante el token de acceso de usuario del sistema de cada app. De forma alternativa, si quieres usar una sola app, puedes reemplazar la URL de devolución de llamada si te suscribes a los webhooks de cada WABA. Consulta Reemplazar la URL de devolución de llamada.

Obtén todas las suscripciones de una WABA

Para obtener una lista de apps suscritas a webhooks de un WABA, envía una solicitud GET al punto de conexión subscribed_apps de el WABA:

Sintaxis de la solicitud

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

Si la respuesta es exitosa, se incluye una variedad de apps que se suscribieron a WABA, con los enlaces, nombres y las propiedades del identificador de cada app.

Ejemplo de solicitud

curl \
'https://graph.facebook.com/v21.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 a una WABA

Para cancelar la suscripción de tu app a los webhooks de una cuenta de WhatsApp Business, envía una solicitud DELETE al punto de conexión subscribed_apps de la 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/v21.0/102289599326934/subscribed_apps' \
-H 'Authorization: Bearer EAAJi...'

Ejemplo de respuesta

{
   "success" : true
}

Reemplazar la URL de devolución de llamada

Consulta Anulación de webhooks.

Configurar las notificaciones

Puedes configurar webhooks para recibir notificaciones de los cambios en tus cuentas de WhatsApp Business suscritas. Estos son los tipos de notificaciones a los que puedes suscribirte:

Campos de suscripción disponibles

Consulta la documentación de Webhooks para cuentas de WhatsApp Business si deseas obtener más información.

Formato de webhooks

Las notificaciones tienen 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 sobre cada campo:

• object
• entry
• changes
• value

Ejemplos

Clientes comerciales registrados

Un webhook account_update se activa con event configurado en PARTNER_ADDED cuando un cliente comercial completa con éxito el proceso de registro insertado.

Sintaxis

{
  "entry": [
    {
      "id": "<BUSINESS_PORTFOLIO_ID>",
      "time": <WEBHOOK_SENT_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "event": "<EVENT>",
            "waba_info": {
              "waba_id": "<CUSTOMER_WABA_ID>",
              "owner_business_id": "<CUSTOMER_BUSINESS_PORTFOLIO_ID>"
            }
          },
          "field": "account_update"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

Ejemplo:

{
  "entry": [
    {
      "id": "35602282435505",
      "time": 1731617831,
      "changes": [
        {
          "value": {
            "event": "PARTNER_ADDED",
            "waba_info": {
              "waba_id": "495709166956424",
              "owner_business_id": "942647313864044"
            }
          },
          "field": "account_update"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

Actualizaciones de números de teléfono

Actualización del nombre recibida

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "field": "phone_number_name_update",
          "value": {
            "display_phone_number": "PHONE_NUMBER",
            "decision": "APPROVED",
            "requested_verified_name": "WhatsApp",
            "rejection_reason": null
          }
        }
      ]
    }
  ]
}

Actualización de calidad recibida

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "field": "phone_number_quality_update",
          "value": {
            "display_phone_number": "PHONE_NUMBER",
            "event": "FLAGGED",
            "current_limit": "TIER_10K"
          }
        }
      ]
    }
  ]
}

Actualizaciones de la cuenta de WhatsApp Business

Número de sandbox actualizado a cuenta verificada

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "phone_number": "PHONE_NUMBER",
            "event": "VERIFIED_ACCOUNT"
          }
        }
      ]
    }
  ]
}

Cuenta de WhatsApp Business bloqueada

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "DISABLED_UPDATE"
            "ban_info": {
              "waba_ban_state": ["SCHEDULE_FOR_DISABLE", "DISABLE", "REINSTATE"],
              "waba_ban_date": "DATE"
            }
          }
        }
      ]
    }
  ]
}

Revisión de la cuenta de WhatsApp Business completada

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "field": "account_review_update",
          "value": {
            "decision": "APPROVED"
          }
        }
      ]
    }
  ]
}

Actualizaciones de la plantilla de mensaje

Aprobada

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <TIMESTAMP>,
      "changes": [
        {
          "value": {
            "event": "APPROVED",
            "message_template_id": <TEMPLATE_ID>,
            "message_template_name": "<TEMPLATE_NAME>",
            "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>",
            "reason": "NONE"
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}