API de la nube

Plataforma de WhatsApp Business > API de la nube

Información general

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

Protocolo HTTP

La API de la nube se basa en la API Graph, por lo que las solicitudes se expresan con el protocolo HTTP y combinaciones de parámetros URL, encabezados y cuerpos de las solicitudes. Por ejemplo, una llamada común a la API de la nube desde la línea de comandos basada en UNIX se ve de la siguiente manera:

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 conoces la API Graph, consulta nuestra documentación de la API Graph para aprender lo básico. Las principales diferencias entre la API Graph y la API de la nube son los tipos de token 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 correspondientes de la documentación de la API de la nube.

Recursos

Estos son los recursos principales con los que interactuarás cuando uses la API.

Portfolio comercial

Para usar la API, debes tener un portfolio comercial. Si no tienes uno, se te pedirá que lo crees como parte de nuestro proceso de primeros pasos. Los portfolios comerciales sirven como contenedor de tu cuentas de WhatsApp Business (WABA) y de tus números de teléfono del negocio.

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

Cuentas de WhatsApp Business

Una cuenta de WhatsApp Business representa a un negocio en la plataforma de WhatsApp Business y se compone principalmente de metadatos sobre un negocio específico. La mayoría de los otros recursos de WhatsApp, como números de teléfono de WhatsApp Business y plantillas de mensajes de WhatsApp, están asociados con una WABA.

Puedes crear una WABA siguiendo los pasos descritos en nuestro documento Primeros pasos. Para obtener más información sobre las WABA y sus limitaciones, consulta Cuentas comerciales de WhatsApp.

Números de teléfono de WhatsApp Business

Un número de teléfono de WhatsApp Business (número de teléfono comercial) representa un número de teléfono real, que, una vez registrado para usar con la API de la nube, se puede utilizar para enviar mensajes a los usuarios de WhatsApp y recibir mensajes de ellos mediante la API.

Los números telefónicos del negocio se componen principalmente de metadatos referidos al número en sí y a tu negocio. Estos metadatos pueden aparecer en el cliente de WhatsApp cuando los usuarios interactúan con tu número de teléfono del negocio.

Puedes crear un número de teléfono del negocio siguiendo los pasos descritos en nuestro documento Primeros pasos. Ten en cuenta que existen restricciones y limitaciones que afectan los números de teléfono del negocio y sus usos, que se describen en detalle en nuestro documento Números de teléfono del negocio.

Plantillas de mensaje de WhatsApp

Las plantillas de mensajes de WhatsApp (plantillas) son personalizables y puedes crearlas mediante la API usando varios componentes de plantilla. Una vez creadas, se revisan automáticamente y, si se aprueban, se pueden usar en 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 los dos, los mensajes de plantilla son los más restrictivos, ya que requieren que se use una plantilla de mensajes de WhatsApp aprobada. Sin embargo, como las plantillas deben someterse a revisión y aprobarse antes de poder usarse, es menos probable que los mensajes de plantilla reciban comentarios negativos de los destinatarios. Los comentarios negativos pueden poner en riesgo tu capacidad de enviar mensajes de cualquier tipo a los clientes.

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 mediante el protocolo HTTP a un punto de conexión público en tu servidor. En gran medida, la API de la nube se basa en webhooks, ya que el contenido de cualquier mensaje enviado desde un usuario de WhatsApp a tu número de teléfono del negocio se enviará como webhook. Asimismo, todas las actualizaciones del estado de entrega de los mensajes salientes se informan mediante webhook.

Ten en cuenta que ofrecemos un ejemplo de una app con webhooks, que puedes clonar en Glitch y usar para realizar las pruebas. La apps solo vuelcan las cargas útiles de los webhooks directamente en una consola para que puedas ver su contenido. Ten en cuenta que es necesario que, en algún momento, compiles tu propio punto de conexión en tu propio servidor, que procesa webhooks de acuerdo con tu propia lógica comercial.

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

Recursos de prueba

Cuando completas por primera vez los pasos descritos en nuestro documento Primeros pasos, se crea automáticamente una WABA y un número de teléfono del negocio, ambos de prueba.

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

Puedes borrar tu portfolio comercial y sus recursos de prueba en los siguientes casos:

  • eres administrador del portfolio comercial asociado a la app
  • no hay otras apps asociadas con el portfolio comercial
  • el portfolio comercial no está asociado con ninguna otra WABA
  • la WABA no está asociada con ningún otro número telefónico del negocio

Si deseas borrar tu portfolio comercial y sus recursos de prueba:

  1. Ve al panel Panel de apps > WhatsApp > Configuración.
  2. Ubica la sección Cuenta de prueba.
  3. Haz clic en el botón Eliminar.

Autenticación y autorización

Tokens de acceso

La API admite tres tipos de tokens:

  • Token de acceso del usuario del sistema
  • Tokens de acceso del usuario del sistema de integración comercial
  • Tokens de acceso del usuario

Consulta nuestros tokens de acceso para determinar qué tipo de token debes usar. Ten en cuenta que los tokens deben ser pasados a través de encabezados de solicitud, y no como un parámetro de cadena de consulta.

Permisos

La API se basa en los siguientes permisos de la API Graph. La combinación exacta de permisos que tu app necesita depende de los puntos de conexión a los que requiere acceder tu app.

  • business_management: se necesita si interactúas con un portfolio comercial.
  • whatsapp_business_management: se necesita si interactúas con una WABA y sus estadísticas, o cualquiera de sus plantillas o números de teléfono del negocio.
  • whatsapp_business_messaging: se necesita para enviar mensajes a los usuarios de WhatsApp y recibir mensajes de ellos.

Estos permisos se conceden generalmente cuando se generan tokens de acceso en Meta Business Suite. Consulta las secciones de generación de tokens en nuestro documento tokens 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 de puntos de conexión pueden incluir un número de versión y que cada versión estará disponible durante aproximadamente 2 años hasta que se retire y ya no sea posible llamarla.

Volumen

En relación con los números de teléfono del negocio registrados, la API de la nube admite, de forma predeterminada, hasta 80 mensajes por segundo (mps) y hasta 1.000 mps por actualización automática.

Este volumen de datos incluye los mensajes entrantes, salientes y todos los demás tipos de mensajes. Ten en cuenta que los números de teléfono del negocio, independientemente del volumen, siguen sujetos al límite de frecuencia de los casos de uso comercial y a los límites de mensajes de plantilla de sus respectivas cuentas de WhatsApp Business.

Si intentas enviar más mensajes de los que permite tu nivel de volumen actual, la API devolverá el código de error 130429 hasta que vuelvas a ubicarte dentro del nivel permitido. Además, los niveles de volumen están pensados para campañas de mensajes que involucran diferentes números de teléfono de usuario de WhatsApp. Si intentas enviar demasiados mensajes al mismo número de usuario de WhatsApp, es posible que obtengas un error relacionado con el límite de frecuencia de emparejamiento.

Mayor volumen

Si cumples con nuestros requisitos de elegibilidad, actualizaremos automáticamente el número de teléfono de tu negocio a 1.000 mps sin que tenga costo para ti. Un mayor volumen no genera gastos adicionales ni afecta los precios.

El proceso de actualización puede tardar hasta 1 minuto. En ese tiempo, no podrás usar el número en nuestra plataforma. Si se usa en una solicitud de la API, la API devolverá el código de error 131057. Después de que se actualice el número de teléfono de un negocio, también se actualizará automáticamente en los aumentos de volumen subsiguientes sin que se produzcan tiempos de inactividad.

Requisitos de elegibilidad

Webhooks

Los servidores de webhooks deberían ser capaces de soportar el triple de la capacidad del tráfico de mensajes salientes y la capacidad del tráfico de mensajes entrantes esperados. Por ejemplo, si se envían 1.000 mps con un índice de respuesta esperado del 30%, los servidores deberían ser capaces de procesar hasta 3.000 webhooks de estado de mensajes, más 300 webhooks de mensajes entrantes.

Nuestra intención es entregar webhooks de forma simultánea, por lo que te recomendamos que configures y pruebes tu servidor de webhooks para que procese solicitudes simultáneas con el siguiente estándar de latencia:

  • La latencia media no debe superar los 250 ms.
  • La latencia es mayor de 1 s menos del 1% de las veces.

Intentaremos volver a entregar los webhooks que no se pudieron entregar durante un plazo de hasta 7 días, con retroceso exponencial.

Mensajes multimedia

Para aprovechar al máximo el mayor volumen, te recomendamos subir tus recursos multimedia a nuestros servidores y usar los identificadores de contenido multimedia que estos devuelven en mensajes multimedia, en lugar de alojar los recursos en los servidores propios y usar las URL de recursos multimedia. Si prefieres (o debes) alojar los recursos en tus propios servidores, te recomendamos usar el almacenamiento en caché de contenido multimedia.

Obtener el nivel de volumen

Utiliza el punto de conexión número de teléfono de WhatsApp Business para obtener el nivel actual de volumen 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 negocio que tiene conexiones múltiples y que ejecuta 2 o más fragmentos de la API de instalaciones locales a la API de la nube, se actualizará de manera automática a un volumen mayor.

Límites de frecuencia

Consulta Límites de frecuencia de la API de administración de WhatsApp Business.

Además de estos límites de frecuencia, contamos con límites más detallados en los recursos individuales, como mensajes de plantilla y números de teléfono comerciales de prueba:

Métricas disponibles

Como usuario de la API de la nube, puedes ver la cantidad de mensajes enviados y entregados, además de otras métricas. Para obtener más información, consulta Obtener métricas de la cuenta.

Escalamiento

Dentro de la infraestructura de Meta, la API de la nube se adapta a escala y se ajusta de forma automática para administrar la carga de trabajo dentro de tu límite de frecuencia (cantidad y volumen de mensajes de cuentas de WABA).

Seguridad y privacidad de datos

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

Cifrado

Con la API de la nube, los mensajes de WhatsApp continuarán contando con la protección del cifrado del protocolo de Signal, que salvaguarda los mensajes antes de que salgan del dispositivo. Gracias a ello, los mensajes que se intercambian con una WABA se entregan de forma segura al destino que eligió cada negocio.

La API de la nube utiliza técnicas de cifrado estándar de la industria para proteger los datos en tránsito y en reposo. La API utiliza la API Graph para enviar mensajes y webhooks para recibir eventos. Ambos operan a través de HTTPS estándar de la industria, protegido por TLS. Si quieres saber más, consulta nuestro informe técnico que contiene información general sobre cifrado.

Consulta nuestro informe técnico con información general sobre cifrado para obtener más información.

Límites de frecuencia de emparejamiento

Los números de teléfono del negocio pueden enviar 1 mensaje cada 6 segundos al mismo número de teléfono de usuario de WhatsApp (0,17 mensajes por segundo). Esto equivale aproximadamente a 10 mensajes por minuto o 600 por hora. Si superas este límite, la API devolverá el código de error 131056 hasta que respetes los valores correspondientes.

Si es necesario, puedes enviar una serie de hasta 45 mensajes en 6 segundos. Básicamente, si envías una serie de mensajes, infringes el límite de frecuencia de emparejamiento, por lo que no podrás enviar más mensajes al mismo usuario hasta que haya transcurrido el tiempo que llevaría normalmente enviar esa cantidad de mensajes por fuera de una serie. Por ejemplo, toma unos 2 minutos enviar a un usuario 20 mensajes fuera de una serie. Por lo tanto, si envías una serie de 20 mensajes, deberás esperar unos 2 minutos para poder enviar otro mensaje a ese usuario.

Si no quieres calcular el tiempo de espera posterior al envío de una serie de mensajes, te recomendamos que, si una solicitud de envío de mensaje no se procesa correctamente después de enviar una serie, vuelvas a intentarlo 4^X segundos después, donde X = 0 y se incrementa de a 1 después de que se produce cada intento fallido, hasta que la solicitud se procesa de forma correcta.

Herramientas

Administrador de WhatsApp

El administrador de WhatsApp es nuestra app web que te permite administrar manualmente recursos de WhatsApp, como WABA, números de teléfono del negocio y plantillas, y permite ver de manera sencilla estadísticas y calificaciones de calidad, o bien los límites de estos recursos. La mayor parte de las funcionalidades que ofrece el administrador de WhatsApp también está disponible a través de la API, con algunas excepciones menores.

Hay varias maneras de acceder al administrador de WhatsApp. En cada una de las rutas, se asume que ya completaste todos los pasos de nuestro documento Primeros pasos.

Mediante Meta Business Suite

  1. Inicia sesión en Meta Business Suite.
  2. Si tienes varios portfolios comerciales, usa el menú desplegable de la izquierda para seleccionar la cuenta que posee la WABA o que tiene acceso a esta y que deseas cargar en el administrador de WhatsApp.
  3. En el menú de la izquierda, ve hasta Cuentas > Cuentas de WhatsApp.
  4. Selecciona la WABA.
  5. En la pestaña Resumen, haz clic en el botón Administrador de WhatsApp.

Mediante el panel de apps

  1. Ve a Mis apps.
  2. Selecciona la app que está asociada con la WABA que deseas cargar en el administrador de WhatsApp.
  3. En el menú de la izquierda, navega hasta WhatsApp > Inicio rápido.
  4. Haz clic en el icono Información de la cuenta que se encuentra en la sección WhatsApp Business.

Mediante URL

Puedes ir directamente a la Información general del administrador de WhatsApp, que muestra todas las WABA que son propiedad de un portfolio comercial determinado, o bien que se comparten con dicho portfolio, si visitas el siguiente enlace:

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

De forma predeterminada, la información general carga la WABA más reciente que creaste o a la que se te concedió acceso, pero puedes usar el menú desplegable de la izquierda para seleccionar el portfolio comercial que contiene la WABA a la que intentas acceder. Sin embargo, al hacerlo, saldrás de la información general. Luego, deberás usar el menú de la izquierda e ir a Cuentas > Cuentas de WhatsApp > (seleccionar la WABA deseada) > Configuración > administrador de WhatsApp (botón).

De manera alternativa, si tienes múltiples portfolios comerciales, puedes agregar el identificador de una cuenta al final de la URL y marcarlo para acceder de manera más fácil:

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

Postman

En nuestro espacio de trabajo de la Plataforma de WhatsApp Business, tenemos una colección Postman de la API de la nube que contiene consultas comunes.