Webhooks para la Plataforma de WhatsApp Business

Blog de WhatsApp Business

Usar Node.js para implementar webhooks

Gracias a los webhooks, podrás recibir notificaciones HTTP en tiempo real de los cambios que se produzcan en determinados objetos. Por ejemplo, podríamos enviarte una notificación cuando un usuario te envíe un mensaje o cuando el estado de una plantilla de mensaje cambie. Esto te ahorra tener que consultar nuestras API sobre los cambios en objetos que se podrían haber producido o no, y te ayuda a evitar alcanzar el límite de frecuencia.

En este documento se proporciona información general sobre los webhooks y cómo se aplican a la API de administración de WhatsApp Business, la API de nube de la Plataforma de WhatsApp Business y la API local de la Plataforma de WhatsApp Business.

Objetos, campos y valores

Cada API puede tener varios tipos de objeto, por lo que siempre debes elegir un tipo de objeto para configurar un webhook. Como cada objeto tiene sus propios campos, el siguiente paso es suscribirte a campos específicos de ese tipo de objeto. Cada vez que se produzca un cambio en el valor de cualquiera de los campos de objeto a los que te hayas suscrito, recibirás una notificación.

Las notificaciones se envían como solicitudes HTTP POST e incluyen una carga útil JSON con la que se describe el cambio.

Webhooks disponibles

En la tabla siguiente se explica la información que puedes recibir de los webhooks.

API	Objetos
API de nube	Un cliente realiza una acción, como responder a un mensaje de una empresa. Un cliente actualiza su número de teléfono. Una empresa envía un mensaje, el mensaje se entrega al cliente o el cliente lee el mensaje; incluye información sobre precios. Se ha producido un error en un mensaje.
API local	Un cliente realiza una acción, como responder a un mensaje de una empresa. Un cliente actualiza su número de teléfono. Una empresa envía un mensaje, el mensaje se entrega al cliente o el cliente lee el mensaje; incluye información sobre precios. Se ha producido un error en un mensaje.
API de administración de WhatsApp Business	Cambios en el estado de una cuenta empresarial oficial y en el estado del nombre para mostrar. El cambio de estado de la revisión de una cuenta de WhatsApp Business. Se ha actualizado información sobre una cuenta de WhatsApp Business, incluida información de infracciones de políticas. Las funciones de una cuenta de WhatsApp Business han cambiado, como un cambio en el número de conversaciones por número de teléfono. Se ha aprobado, rechazado o desactivado una plantilla de mensaje. Se ha aprobado o rechazado el nombre para mostrar asociado a un número de teléfono. El estado relacionado con la calidad de un número de teléfono ha cambiado.

Ejemplo de notificación de un mensaje de texto

En los ejemplos siguientes se representa la notificación de un webhook que se te envía cuando un usuario te ha enviado un mensaje de texto.

API de nube

En el caso de la API de nube, el objeto siempre es whatsapp_business_account, pero field indicará el tipo de información que se envía.

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": PHONE_NUMBER,
          "phone_number_id": PHONE_NUMBER_ID
        },
        "contacts": [{
          "profile": {
            "name": "NAME"
          },
          "wa_id": PHONE_NUMBER
        }],
        "messages": [{
          "from": PHONE_NUMBER,
          "id": "wamid.ID",
          "timestamp": TIMESTAMP,
          "text": {
            "body": "MESSAGE_BODY"
          },
          "type": "text"
        }]
      },
      "field": "messages"
    }]
  }]
}

API local

En el caso de la API local, el objeto será contacts y messages, errors o statuses y pricing, porque el cliente envía el webhook en lugar de Meta.

{
  "contacts": [{
    "profile": {
      "name": "NAME"
    },
    "wa_id": "WHATSAPP_BUSINESS_ACCOUNT_ID"
  }],
  "messages":[{
    "from": "PHONE_NUMBER",
    "id": "wamid.ID",
    "timestamp": "TIMESTAMP",
    "text": {
      "body": "MESSAGE_BODY"
    },
    "type": "text"
  }]
}

Servidor HTTPS

Todos los webhooks se envían mediante HTTPS, por lo que tu servidor debe tener la capacidad de recibir y procesar solicitudes HTTPS. Además, debe tener instalado un certificado TLS/SSL válido. Ten en cuenta que no se admiten los certificados autofirmados.

Más información

Obtén más información sobre los webhooks para una API específica.

Siguientes pasos

Introducción: determina qué API son adecuadas para tu empresa.
Nombre para mostrar: configura el nombre de la empresa que se muestra en los mensajes de WhatsApp.
Números de teléfono: asocia un número de teléfono a tu cuenta de WhatsApp Business.
Precios: obtén información sobre los precios y la configuración de los pagos.

Plataforma de WhatsApp Business | API de nube | API local | API de administración de WhatsApp Business