API de nube

Plataforma de WhatsApp Business > API de nube

Información general

La API de nube, alojada por Meta, permite a medianas y grandes empresas comunicarse con los clientes a escala. Con la API, las empresas pueden crear sistemas que conectan a miles de clientes con agentes o bots, lo que permite una comunicación tanto programática como manual. Además, las empresas pueden integrar la API con numerosos sistemas de back-end, como las plataformas de CRM y de marketing.

Protocolo HTTP

La API de nube se basa en la API Graph, por lo que las solicitudes se expresan mediante el protocolo HTTP y combinaciones de parámetros de URL, encabezados y cuerpos de solicitud. Por ejemplo, una llamada habitual a la API de nube desde una línea de comandos basada en UNIX tiene el siguiente aspecto:

curl 'https://graph.facebook.com/v17.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505555555",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "Here'\''s the info you requested! https://www.meta.com/quest/quest-3/"
  }
}'

Si no tienes experiencia con la API Graph, lee nuestra documentación sobre la API Graph para obtener información acerca de los aspectos básicos. Las principales diferencias entre la API Graph y la API de nube son los tipos de identificadores de acceso que normalmente usarás, los permisos de los recursos, la sintaxis de las solicitudes y la sintaxis de los webhooks. Estas diferencias se describen con mayor detalle en las secciones apropiadas del conjunto de documentación de la API de nube.

Recursos

Estos son los recursos principales con los que interactuarás al usar la API.

Porfolio empresarial

Para usar la API, debes tener un porfolio empresarial. Si no tienes un porfolio, se te pedirá que crees uno como parte de nuestro proceso de introducción. Los porfolios empresariales sirven de contenedor para la cuenta de WhatsApp Business (WABA) y los números de teléfono de empresa.

Para obtener más información sobre los porfolios empresariales, consulta nuestro artículo del Servicio de ayuda Información sobre los porfolios empresariales en Meta Business Suite.

Cuentas de WhatsApp Business

Una cuenta de WhatsApp Business representa una empresa en la Plataforma de WhatsApp Business y se compone principalmente de metadatos sobre una empresa específica. La mayoría de los demás recursos de WhatsApp, como los números de teléfono de WhatsApp Business y las plantillas de mensajes de WhatsApp, están asociados a una cuenta WABA.

Para crear una cuenta WABA, puedes seguir los pasos que se indican en nuestro documento Introducción. Para obtener más información sobre las cuentas WABA y sus limitaciones, consulta Cuentas de WhatsApp Business.

Números de teléfono de WhatsApp Business

Un número de teléfono de WhatsApp Business (número de teléfono de empresa) representa un número de teléfono real, el cual, una vez registrado para usarlo con la API de nube, se puede utilizar para intercambiar mensajes con los usuarios de WhatsApp mediante la API.

Los números de teléfono de empresa se componen principalmente de metadatos sobre el número en sí y la empresa, que pueden aparecer en el cliente de WhatsApp cuando los usuarios interactúan con el número de teléfono de empresa.

Para crear un número de teléfono de empresa, puedes seguir los pasos que se indican en nuestro documento Introducción. Ten en cuenta que existen restricciones y limitaciones en relación con los números de teléfono de empresa y sus usos, que se describen en detalle en nuestro documento Números de teléfono de empresa.

Plantillas de mensajes de WhatsApp

Las plantillas de mensajes de WhatsApp (plantilla) son plantillas personalizables que puedes crear mediante la API con varios componentes de plantillas. Una vez creadas, se revisan automáticamente, y si se aprueban, se pueden usar en los mensajes de plantilla.

Hay dos tipos básicos de mensajes que puedes enviar mediante la API: mensajes de formato libre y mensajes de plantilla. De estos dos tipos, los mensajes de plantilla son los más restrictivos, ya que requieren el uso de una plantilla de mensajes de WhatsApp aprobada. Sin embargo, dado que las plantillas deben someterse a revisión y aprobarse para poder usarse, es menos probable que los mensajes de plantilla reciban comentarios negativos de los destinatarios, lo que puede poner en peligro tu capacidad de enviar mensajes a los clientes por completo.

Para obtener más información sobre las plantillas, consulta nuestro documento Plantillas.

Webhooks

Los webhooks son simplemente cargas útiles JSON que se envían con el protocolo HTTP a un extremo público de tu servidor. La API de nube se basa en gran medida en los webhooks, ya que el contenido de los mensajes enviados desde un usuario de WhatsApp a tu número de teléfono de empresa se enviará como un webhook y todas las actualizaciones de estado de entrega de los mensajes salientes se notifican mediante webhooks.

Ten en cuenta que ofrecemos una aplicación de webhooks de ejemplo que puedes clonar en Glitch y usar para las pruebas. La aplicación solo vuelca las cargas útiles de los webhooks directamente en una consola para que puedas ver su contenido. Ten en cuenta que, en última instancia, tienes que crear tu propio extremo en tu propio servidor a algún punto que digiera los webhooks de acuerdo con tu propia lógica de negocio.

Consulta Webhooks de Meta para obtener más información sobre los webhooks y cómo digerirlos y nuestro documento Webhooks para cuentas de WhatsApp Business.

Recursos de prueba

Cuando completas por primera vez los pasos que se indican en nuestro documento Introducción, se crean automáticamente para ti una cuenta WABA y un número de teléfono de empresa de prueba.

Las cuentas WABA y los números de teléfono de prueba son útiles para realizar pruebas, ya que evitan la mayoría de los límites de mensajes y no requieren un método de pago registrado para enviar mensajes de plantilla.

Puedes eliminar tu porfolio empresarial y sus recursos de prueba si:

  • Eres administrador del porfolio empresarial asociado a la aplicación.
  • No hay otras aplicaciones asociadas al porfolio empresarial.
  • El porfolio empresarial no está asociado a ninguna otra cuenta WABA.
  • La cuenta WABA no está asociada a ningún otro número de teléfono de empresa.

Para eliminar tu porfolio empresarial y sus recursos de prueba:

  1. Accede a la ventana Panel de aplicaciones > WhatsApp > Configuración.
  2. Localiza la sección Cuenta de prueba.
  3. Haz clic en el botón Eliminar.

Autenticación y autorización

Identificadores de acceso

La API admite tres tipos de identificadores:

  • Identificadores de acceso de usuario del sistema
  • Identificadores de acceso de usuario del sistema de integración empresarial
  • Identificadores de acceso de usuario

Consulta nuestros identificadores de acceso para determinar qué tipo de identificador debes usar. Ten en cuenta que los identificadores se deben pasar mediante encabezados de solicitud, no como un parámetro de la cadena de consulta.

Permisos

La API se basa en los siguientes permisos de la API Graph. La combinación exacta de permisos que necesita tu aplicación depende de los extremos a los que accederá.

  • business_management: se necesita si va a interactuar con un porfolio empresarial.
  • whatsapp_business_management: se necesita si va a interactuar con una cuenta WABA y sus análisis o cualquiera de sus plantillas o números de teléfono de empresa.
  • whatsapp_business_messaging: se necesita para intercambiar mensajes con los usuarios de WhatsApp.

Estos permisos se suelen conceder cuando se generan identificadores de acceso en Meta Business Suite. Consulta las secciones de generación de identificadores en nuestro documento Identificadores de acceso.

Control de versiones

El control de versiones usa el protocolo de control de versiones de la API Graph. Esto significa que todas las solicitudes del extremo pueden incluir un número de versión y que cada versión estará disponible durante dos años aproximadamente antes de que se retire y ya no se pueda llamar.

Rendimiento

Para cada número de teléfono de empresa registrado, la API de nube admite un máximo de 80 mensajes por segundo (mps) de manera predeterminada y, mediante una actualización automática, puedes obtener un máximo de 1000 mps.

El rendimiento incluye mensajes entrantes y salientes, y todos los tipos de mensajes. Ten en cuenta que los números de teléfono de empresa, independientemente del rendimiento, siguen sujetos al límite de frecuencia del caso de uso comercial y los límites de mensajes de plantilla de sus cuentas de WhatsApp Business.

Si intentas enviar más mensajes de los que permite tu nivel de rendimiento actual, la API devolverá el código de error 130429 hasta que vuelvas al nivel permitido. Además, los niveles de rendimiento están destinados a campañas de mensajes que involucran números de teléfono de diferentes usuarios de WhatsApp. Si intentas enviar demasiados mensajes al número del mismo usuario de WhatsApp, puede surgir un error límite de frecuencia del par (código de error 131056).

Mayor rendimiento

Si cumples nuestros requisitos de idoneidad, actualizaremos tu número de teléfono de empresa a 1000 mps automáticamente sin coste alguno para ti. Un mayor rendimiento no implica cobros adicionales ni afecta a los precios.

El proceso de actualización en sí puede tardar un máximo de un minuto. Durante este tiempo, el número no se podrá usar en nuestra plataforma. Si se utiliza en una solicitud a la API, esta devolverá el código de error 131057. Una vez que se haya actualizado un número de teléfono de empresa, se actualizará automáticamente para cualquier futuro aumento de rendimiento sin tiempo de inactividad.

Requisitos

Webhooks

Los servidores de webhooks deben poder soportar el triple de capacidad de tráfico de mensajes salientes, así como la capacidad total de tráfico esperado de mensajes entrantes. Por ejemplo, si se envían 1000 mps con un índice de respuesta esperado del 30 %, los servidores deben poder procesar 3000 webhooks de estado del mensaje y 300 webhooks adicionales de mensajes entrantes.

Intentamos entregar los webhooks simultáneamente, por lo que recomendamos que configures y pruebes el servidor de webhooks para que pueda gestionar solicitudes simultáneas con el siguiente estándar de latencia:

  • La mediana de latencia no debe superar los 250 ms.
  • Menos del 1 % de la latencia supera 1 s.

Intentaremos volver a entregar los webhooks con errores durante un máximo de siete días, con un retroceso exponencial.

Mensajes multimedia

Para aprovechar al máximo el mayor rendimiento, recomendamos subir los activos multimedia a nuestros servidores y usar los identificadores de contenido devueltos en mensajes multimedia en lugar de alojar los activos en tus servidores y utilizar URL de activos multimedia. Si prefieres (o debes) alojar los activos en servidores propios, recomendamos usar el almacenamiento en caché de contenido multimedia.

Obtener el nivel de rendimiento

Utiliza el extremo del número de teléfono de WhatsApp Business para obtener el nivel de rendimiento actual de un número de teléfono:

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput

Migración

Si migras un número de teléfono de empresa que tenga una conexión múltiple y ejecute dos o más particiones de la API local a la API de nube, se actualizará automáticamente a un rendimiento superior.

Límites de frecuencia

Las cuentas WABA tienen un límite de frecuencia de recuento de llamadas a la API. Todas las llamadas a la API que realice tu aplicación a un número de teléfono de empresa de una cuenta WABA (es decir, al nodo del número de teléfono de WhatsApp Business o a cualquiera de sus perímetros, como el extremo de mensajes) se tienen en cuenta para el límite.

El límite actual son 11 880 000 llamadas a la API por periodo renovable de una hora para cada WABA.

Por ejemplo, durante un periodo de una hora, la aplicación podría realizar 11 880 000 llamadas a la API con un número de teléfono de WhatsApp Business asociado a una cuenta WABA A y otras 11 880 000 llamadas con un número de teléfono de WhatsApp Business asociado a una cuenta WABA B. De igual manera, durante un periodo de una hora, la aplicación podría realizar hasta 11 880 000 llamadas a la API en total usando una combinación de distintos números de teléfono de WhatsApp Business asociados a una sola cuenta WABA.

Si alcanzas el límite, la API devolverá el código de error80007.

Ten en cuenta que la API de administración de WhatsApp Business tiene límites de frecuencia distintos. Consulta Límites de frecuencia de la API de WhatsApp Business.

Además de estos límites de frecuencia, tenemos otros límites granulares aplicables a recursos individuales, como los mensajes de plantilla y los números de teléfono de empresa de prueba:

Resultados disponibles

Como usuario de la API de nube, puedes ver el número de mensajes enviados y entregados, así como otras métricas. Para más información, consulta Obtención de métricas de la cuenta.

Adaptación

En la infraestructura de Meta, la API de nube se adapta y ajusta de forma automática para gestionar la carga de trabajo dentro del límite de frecuencia (volumen de mensajes y número de cuentas WABA).

Seguridad y privacidad de los datos

Consulta la información general sobre seguridad y privacidad para obtener más información.

Cifrado

Con la API de nube, todos los mensajes de WhatsApp continúan protegidos mediante el cifrado del protocolo Signal, que salvaguarda los mensajes antes de que salgan del dispositivo. Esto quiere decir que los mensajes intercambiados con una cuenta WABA se entregan de forma segura en el destino que cada empresa elige.

La API de nube utiliza técnicas de cifrado estándar del sector para proteger los datos en tránsito y en reposo. La API usa la API Graph para enviar mensajes y webhooks para recibir eventos, y ambos servicios operan con un protocolo HTTPS estándar del sector protegido mediante TLS. Consulta nuestro informe de introducción al cifrado para obtener más información.

Consulta nuestro informe de introducción al cifrado para obtener más información.

Herramientas

Administrador de WhatsApp

El Administrador de WhatsApp es nuestra aplicación web que te permite administrar manualmente recursos de WhatsApp, como cuentas WABA, plantillas y números de teléfono de empresa, y facilita la visualización de los insights y las calificaciones de calidad o los límites de estos recursos. La mayoría de las funciones que ofrece el Administrador de WhatsApp también están disponibles mediante la API, con algunas excepciones.

Hay varias maneras de acceder al Administrador de WhatsApp. En todas ellas se presupone que ya has completado todos los pasos descritos en nuestro documento Introducción.

Mediante Meta Business Suite

  1. Inicia sesión en Meta Business Suite.
  2. Si tienes varios porfolios empresariales, usa el menú desplegable de la izquierda para seleccionar la cuenta que es propietaria de la cuenta WABA que quieres cargar en el Administrador de WhatsApp o que tiene acceso a ella.
  3. En el menú de la izquierda, ve a Cuentas > Cuentas de WhatsApp.
  4. Selecciona la cuenta WABA.
  5. En la pestaña Resumen, haz clic en el botón Administrador de WhatsApp.

Mediante el panel de aplicaciones

  1. Ve a Mis aplicaciones.
  2. Selecciona la aplicación asociada a la cuenta WABA que quieres cargar en el Administrador de WhatsApp.
  3. En el menú de la izquierda, ve a WhatsApp > Inicio rápido.
  4. En la sección WhatsApp Business, haz clic en Información de la cuenta.

Mediante una URL

Puedes dirigirte directamente a Información general del Administrador de WhatsApp, donde se muestran todas las cuentas WABA que son propiedad de un porfolio empresarial concreto o se han compartido con él; para ello, accede al siguiente enlace:

https://business.facebook.com/wa/manage/home/

De forma predeterminada, la información general carga la cuenta WABA que has creado o a la que se te ha concedido acceso más recientemente, pero puedes utilizar el menú desplegable de la izquierda para seleccionar el porfolio empresarial que contenga la cuenta WABA a la que intentas acceder. Sin embargo, esta acción te hará salir de la información general y deberás utilizar el menú de la izquierda para ir a Cuentas > Cuentas de WhatsApp > (selecciona la cuenta WABA que quieras) > Configuración > Administrador de WhatsApp (botón).

Como alternativa, si tienes varios porfolios empresariales, puedes añadir el identificador de una cuenta al final de la URL y marcarla para facilitar el acceso:

https://business.facebook.com/wa/manage/home/?business_id=<META_BUSINESS_ACCOUNT_ID>

Postman

Tenemos una colección de Postman de la API de nube con consultas habituales en nuestro espacio de trabajo de la Plataforma de WhatsApp Business.