API de administración de WhatsApp Business

Componentes de webhooks

Los webhooks tienen un campo de matriz de nivel superior que indica lo que se está comunicando. Los miembros de la matriz son objetos JSON con campos detallados relevantes para el webhook.

Los webhooks de la API de Administrador de WhatsApp Business pueden contener los objetos siguientes:

ParámetroDescripción

object

Objeto de la suscripción.


En el caso del registro insertado, siempre es whatsapp_business_account.

entry

Este objeto contiene los detalles del cambio que activó la llamada de webhooks.

Objeto entry

ParámetroDescripción

id

Identificador de las cuentas de Whatsapp Business a las que pertenece el webhook.

time

Hora de la entrada.

changes

Cambios que activaron la llamada de Webhooks. Consulta el objeto changes.

changes

ParámetroDescripción (Haz clic en la flecha de la columna de la izquierda para consultar los valores admitidos)

field

Contiene el tipo de notificación que recibes para el webhook.

Valores admitidos

  • account_alerts
  • account_review_update
  • account_update
  • business_capability_update
  • message_template_quality_update
  • message_template_status_update
  • phone_number_name_update
  • phone_number_quality_update
  • security
  • template_category_update

value

Contiene detalles de los cambios relacionados con el campo field especificado. Consulta el objeto value.

value

ParámetroDescripción (Haz clic en la flecha de la columna de la izquierda para consultar los valores admitidos)

ban_info

Se añade a los webhooks cuando se bloquea una cuenta. Este objeto incluye dos propiedades:

  • waba_ban_state; las opciones son:
    • DISABLE
    • REINSTATE
    • SCHEDULE_FOR_DISABLE
  • waba_ban_date

current_limit

Contiene el límite del nivel actual de la cuenta.

Valores admitidos

  • TIER_50
  • TIER_250
  • TIER_1K
  • TIER_10K
  • TIER_100K
  • TIER_UNLIMITED

decision

Se usa si se ha tomado una decisión sobre las cuentas o los números de teléfono.

Valores admitidos

  • APPROVED
  • REJECTED

display_phone_number

Incluye el número de teléfono para mostrar de la cuenta empresarial que activó la notificación.

event

Se usa cuando se produce un evento en una cuenta WABA concreta. Haz clic en la flecha de la columna de la izquierda para ver todas las opciones disponibles.

Actualizaciones del nombre para mostrar

  • APPROVED: la revisión se ha aprobado. Si anteriormente una empresa no podía descargar el certificado, ahora debería poder usar su nombre para mostrar si descarga el certificado.
  • DEFERRED: la revisión se ha aplazado y la empresa puede usar su nombre para mostrar si descarga el certificado.
  • REJECTED: la revisión se ha rechazado con el motivo indicado. Si anteriormente una empresa no podía descargar el certificado, tiene que volver a solicitar una revisión del nombre para mostrar a fin de obtener acceso al certificado. Si una empresa ya está usando su certificado, el rechazo de la revisión del nombre para mostrar no afecta a su operación. No obstante, es necesario aprobar la revisión para que la empresa aumente los límites de cuentas y mensajes.

Actualización de la calidad de las plantillas de mensajes

Puntuaciones de calidad anteriores:


  • GREEN
  • RED
  • UNKNOWN
  • YELLOW

Nuevas puntuaciones de calidad:


  • GREEN
  • RED
  • UNKNOWN
  • YELLOW

Actualizaciones de estado de las plantillas de mensajes

  • APPROVED
  • DISABLED
  • IN_APPEAL
  • PENDING
  • REINSTATED
  • REJECTED
  • FLAGGED

Actualizaciones del número de teléfono

  • DOWNGRADE
  • FLAGGED
  • ONBOARDING
  • UNFLAGGED
  • UPGRADE

Actualización de las categorías de plantillas

Categorías anteriores:


  • MARKETING
  • OTP
  • TRANSACTIONAL

Nuevas categorías:


  • AUTHENTICATION
  • MARKETING
  • UTILITY

Código de verificación en dos pasos

  • PIN_CHANGED: el código de verificación en dos pasos se ha actualizado (solo en el caso de la API de nube).
  • PIN_RESET_REQUEST: solicitud para inhabilitar el código de verificación en dos pasos.
  • PIN_RESET_SUCCESS: el código de verificación en dos pasos se ha desactivado.

Actualizaciones de la cuenta WABA

  • ACCOUNT_RESTRICTION: se usa para informar de que se ha aplicado una restricción cuando una cuenta WABA incumple las políticas de la Plataforma de WhatsApp Business.
  • DISABLED_UPDATE
  • VERIFIED_ACCOUNT

max_daily_conversation_per_phone

Siempre está presente cuando field=business_capability_update.


Indica el número de mensajes de plantilla que puedes enviar con cada número de teléfono de empresa de tu cuenta de WhatsApp Business con un nombre para mostrar aprobado. Consulta Límites de mensajes.

max_phone_numbers_per_business

Incluye el número máximo de números de teléfono que pueden pertenecer a una empresa.


Cuando field=business_capability_update, un webhook incluirá max_phone_numbers_per_business o max_phone_numbers_per_waba.

max_phone_numbers_per_waba

Incluye el número máximo de números de teléfono que pueden pertenecer a una cuenta WABA.


Cuando field=business_capability_update, un webhook incluirá max_phone_numbers_per_business o max_phone_numbers_per_waba.

reason

Motivo de rechazo de la plantilla. Posibles valores:


  • ABUSIVE_CONTENT: el contenido se considera ofensivo.
  • INCORRECT_CATEGORY: la categoría se considera incorrecta. Consulta Categorías de plantillas.
  • INVALID_FORMAT: contenido duplicado o faltan ejemplos.
  • NONE: valor predeterminado, se establece cuando se aprueba la plantilla.
  • SCAM: el contenido se considera fraudulento.

rejection_reason

Si se rechazó una solicitud, este campo muestra el motivo del rechazo.

requested_verified_name

Este campo muestra el nombre que se envió para su verificación.

restriction_info

Enumeración

Se usa para informar de restricciones que se han impuesto en una cuenta WABA concreta, cuando dicha cuenta WABA incumple las políticas de la Plataforma de WhatsApp Business.


Este campo incluye una lista de tipos de restricción y sus fechas de caducidad respectivas. Los posibles tipos de restricción son los siguientes:


  • RESTRICTED_ADD_PHONE_NUMBER_ACTION
  • RESTRICTED_BIZ_INITIATED_MESSAGING
  • RESTRICTED_CUSTOMER_INITIATED_MESSAGING

Las fechas de caducidad se proporcionan en el formato DateTime.

requester

Identificador del usuario que solicitó desactivar, o ya ha desactivado o actualizado, el código de verificación en dos pasos.

Ejemplos

Actualización de estado de las plantillas de mensajes

Plantilla aprobada

{
  "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 
         }
       }
      ]
    }
  ]
}

Plantilla rechazada

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

Plantilla programada para su inhabilitación

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "field": "message_template_status_update",
          "value": { 
              "event": "FLAGGED",
              "message_template_id": TEMPLATE-ID, 
              "message_template_name": "My message template",
              "message_template_language": "en-US",
              "reason": null,
              "disable_info": {
                  "disable_date": "DATE",
              }
         }
       }
      ]
    }
  ]
}

Plantilla pausada

{
  "object": "whatsapp_business account",
  "entry": [
    {
      "id": "10908...",
      "time": 1661885238,
      "changes": [
        {
          "value": {
            "event": "PAUSED",
            "message_template_id": 6048...,
            "message_template_name": "welcome",
            "message_template_language": "en_US",
            "reason": "NONE",
            "other_info": {
              "title": "SECOND_PAUSE",
              "description": "Your WhatsApp message template has been paused for 6 hours until Aug 31 at 12:47 AM UTC because it continued to have issues."
            }
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ],
}

Mensaje de plantilla pendiente de eliminación

{
  "object": "whatsapp_business account",
  "entry": [
    {
      "id": "10310...",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "PENDING_DELETION",
            "message_template_id": 1137...,
            "message_template_name": "<MY_TEMPLATE_NAME>",
            "message_template_language": "en_US",
            "reason": "NONE"            
            }
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ],
}

Actualización de las categorías de plantillas

Cambio de categoría de plantilla

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<ID>",
      "time": <TIME>,
      "changes": [
        {
          "field": "template_category_update",
          "value": {            
            "message_template_id": <MESSAGE_TEMPLATE_ID>,
            "message_template_name": "<MESSAGE_TEMPLATE_NAME>",
            "message_template_language": "<MESSAGE_TEMPLATE_LANGUAGE",
            "previous_category": "<PREVIOUS_CATEGORY>",
            "new_category": "<NEW_CATEGORY>"
          }
        }
      ]
    }
  ]
}

Actualización de calidad de la plantilla de mensaje

Cambio de calificación de calidad de plantilla

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <TIMESTAMP>,
      "changes": [
        {
          "field": "message_template_quality_update",
          "value": {
            "previous_quality_score": "<PREVIOUS_QUALITY_SCORE>",
            "new_quality_score": "<NEW_QUALITY_SCORE>",
            "message_template_id": <TEMPLATE_ID>,
            "message_template_name": "<TEMPLATE_NAME>",
            "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>"
          }
        }
      ]
    }
  ]
}

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"
            }
          }
        }
      ]
    }
  ]
}

Infracción de la política por parte de la cuenta de WhatsApp Business

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "ACCOUNT_VIOLATION",
            "violation_info": {
              "violation_type": "VIOLATION_TYPE"
            }
          },
          "field": "account_update"
        }
      ]
    }
  ]
}

Restricción de la cuenta de WhatsApp Business tras una infracción de la política

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "ACCOUNT_RESTRICTION",
            "restriction_info": [
               {"restriction_type": 
                 "RESTRICTED_BIZ_INITIATED_MESSAGING" | 
                 "RESTRICTION_ON_ADD_PHONE_NUMBER_ACTION" | 
                 "RESTRICTED_CUSTOMER_INITIATED_MESSAGING", 
                 "expiration": TIMESTAMP}
                 ]
            }
          },
          "field": "account_update"
        }
      ]
    }
  ]
}

Cuenta de WhatsApp Business desactivada

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

Revisión de la 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"
          }
        }
      ]
    }
  ]
}

Restricción de la cuenta de WhatsApp Business debido a infracciones de la política

{
  "field": "account_update",
  "value": {
    "phone_number": "PHONE_NUMBER",
    "event": "ACCOUNT_RESTRICTION",
    "restriction_info": [
      {
        "restriction_type": "RESTRICTION_ADD_PHONE_NUMBER_ACTION",
        "expiration": TIMESTAMP
      },
      {
        "restriction_type": "RESTRICTED_BIZ_INITIATED_MESSAGING",
        "expiration": TIMESTAMP
      },
      {
        "restriction_type": "RESTRICTED_CUSTOMER_INITIATED_MESSAGING",
        "expiration": TIMESTAMP
      }
    ]
  }
}

Cuenta de WhatsApp Business eliminada

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

Cuenta de WhatsApp Business suprimida del socio

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

Actualizaciones de las funciones de la empresa

{
    "object": "whatsapp_business_account",
    "entry": [
      {
        "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
        "time": TIMESTAMP,
        "changes": [
          {
            "field": "business_capability_update",
            "value": {
              "max_daily_conversation_per_phone": NUMBER,
              "max_phone_numbers_per_business": NUMBER
            }
          }
        ]
      }
    ]
  }

Alertas de la cuenta

Aumento del límite de mensajes denegado

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <UNIX_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "entity_type": "BUSINESS",
            "entity_id": "<BUSINESS_ID>",
            "alert_severity": "CRITICAL",
            "alert_status": "ACTIVE",
            "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_FAILED",
            "alert_description": "Based on your activity, limits cannot be increased for your business <BUSINES_NAME>. Contact support for more information."
          },
          "field": "account_alerts"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

Aumento del límite de mensajes denegado, se requiere más uso

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <UNIX_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "entity_type": "BUSINESS",
            "entity_id": "<BUSINESS_ID>",
            "alert_severity": "WARNING",
            "alert_status": "ACTIVE",
            "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED",
            "alert_description": "Limits cannot be increased for your business <BUSINES_NAME>. Use WhatsApp Business platform actively for several days and follow our messaging policies."
          },
          "field": "account_alerts"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

Aumento del límite de mensajes denegado, se requiere más información

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <UNIX_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "entity_type": "BUSINESS",
            "entity_id": "<BUSINESS_ID>",
            "alert_severity": "WARNING",
            "alert_status": "ACTIVE",
            "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_NEED_MORE_INFO",
            "alert_description": "Additional verification is required for your business <BUSINESS_NAME>. Go to Security Center in Meta for Business to complete identity verification. To continue without completing additional verification, your business can use WhatsApp Business platform actively for several days and follow our messaging policies."
          },
          "field": "account_alerts"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}