API de administración de WhatsApp Business

Componentes de webhooks

Los webhooks tienen un campo matriz principal que indica qué se está comunicando. Los miembros de la matriz serán objetos JSON con campos detallados relevantes para el webhook.

Los webhooks de la API de administración de WhatsApp Business pueden contener los siguientes objetos:

ParámetroDescripción

object

Este es el objeto al que te suscribiste.


Siempre es whatsapp_business_account para los registros insertados.

entry

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

El objeto entry

ParámetroDescripción

id

ID de las cuentas de WhatsApp Business a las que pertenece este webhook.

time

Hora de la entrada.

changes

Cambios que activaron la llamada a los webhooks. Consulta el objeto changes.

changes

ParámetroDescripción (haz clic en la flecha de la columna izquierda para ver los valores compatibles)

field

Contiene el tipo de notificación que recibes en ese 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 field especificado. Consulta el objeto value.

value

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

ban_info

Se agrega 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 de nivel actual en el que se encuentra esta cuenta.

Valores admitidos

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

decision

Se utiliza si se tomó una decisión en relación con las cuentas o los números de teléfono.

Valores admitidos

  • APPROVED
  • REJECTED

display_phone_number

Incluye el número de teléfono de la cuenta comercial que activó esta notificación.

event

Se usa cuando se produce un evento en una cuenta específica de WhatsApp Business. Haz clic en la flecha de la columna izquierda para ver todas las opciones disponibles.

Actualizaciones del nombre para mostrar

  • APPROVED: se aprobó la revisión. Si anteriormente una empresa no pudo descargar su certificado, ahora sí debería poder descargarlo y usar el nombre para mostrar.
  • DEFERRED: se postergó la revisión y la empresa puede descargar el certificado y usar su nombre para mostrar.
  • REJECTED: se rechazó la revisión y se incluye el motivo correspondiente. Si anteriormente una empresa no pudo descargar su certificado, debería solicitar nuevamente una revisión del nombre para mostrar a fin de poder acceder al certificado. Si una empresa ya está utilizando su certificado, el rechazo de la revisión del nombre para mostrar no afecta sus operaciones. Sin embargo, es necesario que la empresa pase la revisión para aumentar los límites de mensajes y de su cuenta.

Actualización de la calidad de la plantilla de mensaje

Puntuación de calidad anterior:


  • GREEN
  • RED
  • UNKNOWN
  • YELLOW

Nueva puntuación de calidad:


  • GREEN
  • RED
  • UNKNOWN
  • YELLOW

Actualizaciones de estado de la plantilla de mensaje

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

Actualizaciones de números de teléfono

  • DOWNGRADE
  • FLAGGED
  • ONBOARDING
  • UNFLAGGED
  • UPGRADE

Actualización de la categoría de la plantilla

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 está actualizado (API de la nube únicamente)
  • PIN_RESET_REQUEST: solicitud para desactivar el código de verificación en dos pasos
  • PIN_RESET_SUCCESS: el código de verificación en dos pasos está desactivado

Actualizaciones de la cuenta de WhatsApp Business

  • ACCOUNT_RESTRICTION: se usa para reportar que se impuso una restricción cuando una cuenta de WhatsApp Business infringe las políticas de la Plataforma de WhatsApp Business.
  • DISABLED_UPDATE
  • VERIFIED_ACCOUNT

max_daily_conversation_per_phone

Siempre presente si field=business_capability_update.


Indica la cantidad de mensajes de plantilla que puedes enviar con cada número de teléfono del negocio de tus cuentas de WhatsApp Business que tienen 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.


Si field=business_capability_update, un webhook tendrá 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 WABA.


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

reason

Motivo del rechazo de la plantilla. Valores posibles:


  • ABUSIVE_CONTENT: se determinó que el contenido es abusivo.
  • INCORRECT_CATEGORY: se determinó que la categoría es incorrecta. Consulta Categorías de plantillas.
  • INVALID_FORMAT: el contenido está duplicado o faltan ejemplos.
  • NONE: valor predeterminado; se establecerá cuando se apruebe la plantilla.
  • SCAM: se determinó que el contenido es una estafa.

rejection_reason

Si se rechaza 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 reportar restricciones impuestas a una cuenta de WhatsApp Business cuando esta infringe las políticas de la plataforma de WhatsApp Business.


Este campo incluye una lista de los tipos de restricciones y las fechas de vencimiento correspondientes. Los tipos de restricciones posibles son los siguientes:


  • RESTRICTED_ADD_PHONE_NUMBER_ACTION
  • RESTRICTED_BIZ_INITIATED_MESSAGING
  • RESTRICTED_CUSTOMER_INITIATED_MESSAGING

Las fechas de vencimiento se muestran en formato DateTime.

requester

Identificador del usuario que solicitó la inhabilitación del código de verificación en dos pasos, o bien que ya lo inhabilitó o actualizó.

Ejemplos

Actualización del estado de la plantilla de mensaje

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

Eliminación del mensaje de plantilla pendiente

{
  "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 la categoría de la plantilla

Categoría de la plantilla modificada

{
  "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 la calidad de la plantilla de mensaje

Cambio de la calificación de calidad de la 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 de 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 de WhatsApp Business

Número de sandbox actualizado 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"
            }
          }
        }
      ]
    }
  ]
}

La cuenta de WhatsApp Business infringe la política

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

Cuenta de WhatsApp Business restringida por infringir 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 inhabilitada

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

Cuenta de WhatsApp Business restringida 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 eliminada 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 la funcionalidad comercial

{
    "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 cuenta

Aumento del límite de mensajes rechazado

{
  "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 rechazado; 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 rechazado; 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"
}