WhatsApp Cloud API: qué es, cómo funciona y cómo empezar

La Cloud API es la API de la WhatsApp Business Platform que Meta aloja en su propia infraestructura. Tu sistema no instala nada: hace llamadas HTTPS para enviar y recibe eventos en un endpoint tuyo.

Según la documentación de Meta, la Cloud API cubre tres capacidades: mensajería (texto, multimedia, plantillas y mensajes interactivos), llamadas (hacer y recibir llamadas de voz) y grupos (crear y gestionar grupos de WhatsApp). Se complementa con la Business Management API, que administra las cuentas, los números, las plantillas y las métricas.

• Sin servidores propios: Meta opera la infraestructura, el escalado y las actualizaciones. Meta informa una disponibilidad del 99,9 % y una latencia p99 menor a 5 segundos.
• Cifrado: cada mensaje sigue protegido con el protocolo Signal, y las llamadas a Graph API y los webhooks viajan por HTTPS con TLS.
• Funciones nuevas solo aquí: desde enero de 2024 las funciones nuevas salen en la Cloud API y ya no en On-Premises.
• Varios sistemas sobre el mismo número: tu CRM, tu bandeja de agentes y un Agente IA pueden operar sobre un mismo número a través de tu integración o tu proveedor.

No exactamente. La Business Platform es el conjunto de productos; “WhatsApp Business API” es el nombre popular de esa plataforma; la Cloud API es la API concreta que envía y recibe.

La Cloud API funciona con dos piezas: llamadas HTTPS a Graph API para enviar y administrar, y webhooks que Meta envía a tu servidor para avisarte lo que pasa. Las respuestas llegan en JSON.

Así se ve el envío de un mensaje de texto, que solo funciona dentro de una ventana de 24 horas abierta:

curl 'https://graph.facebook.com/v26.0/<PHONE_NUMBER_ID>/messages' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "<NUMERO_DEL_USUARIO>",
    "type": "text",
    "text": { "body": "Hola, ¿en qué te puedo ayudar?" }
  }'

Fuera de esa ventana, el mismo endpoint se usa con "type": "template" y una plantilla aprobada.

Qué tiene que hacer tu webhook

• Verificación (GET): al configurar la URL, Meta envía hub.mode=subscribe, hub.challenge y hub.verify_token. Si el token coincide con el tuyo, respondes HTTP 200 con el valor de hub.challenge.
• Eventos (POST): cada evento llega con el encabezado X-Hub-Signature-256, un HMAC-SHA256 del cuerpo calculado con el app secret de tu app. Compáralo antes de procesar.
• Certificado válido: el endpoint necesita un certificado TLS válido; los autofirmados no se aceptan. Puedes sumar TLS mutuo (mTLS).
• Duplicados: si no respondes 200, Meta reintenta durante hasta 7 días, así que puedes recibir el mismo evento más de una vez. Deduplica por el identificador del mensaje.
• Tamaño y lotes: cada payload pesa hasta 3 MB y Meta puede agrupar hasta 1.000 actualizaciones por envío, aunque no lo garantiza.
• Sin historial: no hay API para recuperar webhooks pasados; guarda lo que necesites al recibirlo.
• Modo de la app: algunos webhooks no se envían mientras la app está en modo Desarrollo; pásala a modo Live antes de producción.

Los estados de cada mensaje y cómo interpretarlos están en estados de mensajes y webhooks, y los códigos de error, en errores de la WhatsApp Business API. Si el usuario adoptó un nombre de usuario, el webhook puede identificarlo con su BSUID además del número.

Límites de solicitudes que conviene conocer

• Business Management API: 200 solicitudes por hora por app y por Messaging account, por defecto; 5.000 por hora si la cuenta está activa y tiene al menos un número registrado.
• Mismo usuario: puedes enviar 1 mensaje cada 6 segundos a una misma persona (unos 10 por minuto). Se admiten ráfagas de hasta 45 mensajes, pero después tienes que esperar. Si te pasas, recibes el error 131056.

Registrar un número es lo que lo habilita para enviar y recibir por la Cloud API. Primero lo agregas y verificas que es tuyo; después lo registras con una llamada a la API, que es la única vía: no se puede registrar desde WhatsApp Manager ni desde el App Dashboard.

1. Agrégalo a tu WhatsApp account desde WhatsApp Manager (hoy se entra por la Messaging account) o con el Embedded Signup de tu proveedor.
2. Verifica que es tuyo con el código que llega por SMS o por llamada de voz.
3. Regístralo por API con POST /<PHONE_NUMBER_ID>/register, "messaging_product": "whatsapp" y un pin de 6 dígitos. Si el número ya tenía verificación en dos pasos, usas ese PIN; si no, el que envíes queda como PIN nuevo. Meta está retirando ese PIN para los números elegibles, pero el registro sigue pidiendo un valor válido.

Qué tipos de línea funcionan mejor (fija, móvil, virtual o 0800) está en número virtual para WhatsApp Business. Para subir el tope de números, revisa cómo verificar tu empresa en Meta.

Cada llamada a la Cloud API lleva un token de acceso en el encabezado Authorization: Bearer. El tipo de token depende de quién eres: una empresa que integra su propia cuenta o un proveedor que atiende clientes.

• Permisos: el token del usuario del sistema necesita business_management, whatsapp_business_management y whatsapp_business_messaging.
• Acceso a las dos cuentas: el usuario del sistema necesita acceso parcial o total a la WhatsApp account y a la Messaging account. Si le falta, la API responde con el error 200 (no confundir con el HTTP 200).
• Formato: los tokens son cadenas opacas de largo variable. No los interpretes y guárdalos sin un tamaño máximo fijo, en un lugar seguro.

El throughput es la cantidad de mensajes por segundo (mps) que procesa cada número registrado. La Cloud API admite 80 mps por defecto y hasta 1.000 mps con una mejora automática y sin costo.

• Si superas tu throughput, la API devuelve el error 130429 hasta que vuelvas al nivel permitido.
• La mejora a 1.000 mps puede dejar el número fuera de servicio hasta 1 minuto (error 131057). Las mejoras siguientes no tienen corte.
• Meta recomienda que tu webhook soporte 3 veces el tráfico saliente en estados más el tráfico entrante esperado, con una latencia mediana de 250 ms o menos.
• Para aprovechar el máximo, sube los archivos multimedia a Meta y envía su ID en lugar de una URL propia.

El límite de mensajería es la cantidad de usuarios únicos a los que puedes entregar mensajes fuera de la ventana de servicio en 24 horas móviles. Se define por business portfolio y lo comparten todos sus números (y los proveedores que operan un mismo número).

• Desde el 7 de octubre de 2025, si la calidad baja, Meta ya no reduce el límite: frena el escalado y, ante infracciones, puede aplicar sanciones.
• Tu límite actual aparece en WhatsApp Manager y por API en el campo whatsapp_business_manager_messaging_limit (el viejo messaging_limit_tier está deprecado).
• Plantillas: hasta 250 por Messaging account si el portfolio no está verificado, y hasta 6.000 si está verificado y tiene un nombre visible aprobado. Se crean como máximo 100 por hora.

El detalle de cada escalón y cómo subir rápido está en límites de mensajería de WhatsApp.

Embedded Signup es el flujo con el que un proveedor da de alta a una empresa en la Cloud API sin que esta toque código: la empresa inicia sesión, crea o elige sus cuentas, verifica su número y le da acceso al proveedor. La versión 4 es la vigente.

• Qué hace la empresa en el flujo: se identifica con su cuenta de Facebook o de Meta Business, acepta los términos, elige o crea su business portfolio y su WhatsApp account, verifica el número y carga el nombre visible.
• Qué hace el proveedor después: intercambia el código por un token de integración, registra el número, suscribe su app a los webhooks de la Messaging account del cliente y, si es Solution Partner, comparte su línea de crédito. Si es Tech Provider, el cliente carga su propio método de pago.
• Versión 4: disponible desde el 8 de octubre de 2025. Permite dar de alta en un solo flujo la Cloud API, la Marketing Messages API, los anuncios que hacen clic a WhatsApp y la Conversions API.
• Deprecación: Embedded Signup v2 y v3, incluidas sus vistas previas, se deprecan el 15 de octubre de 2026. Si tu proveedor todavía usa esas versiones, pregúntale cuándo migra.
• Propiedad: la empresa es dueña de todos sus activos de WhatsApp y tiene acceso completo a WhatsApp Manager; el proveedor no puede restringirlo.
• Límites para proveedores: 10 clientes nuevos cada 7 días por defecto, y 200 cuando el proveedor completa Business Verification, App Review y Access Verification.

Embedded Signup también es el camino para Coexistence: conecta un número de la Business App sin volver a registrarlo.

La WhatsApp Business Account (WABA) se divide en dos: la WhatsApp account, con tus números y tu identidad, y la Messaging account, con tus plantillas, tu facturación y tus suscripciones a webhooks. Meta lo despliega desde el 23 de septiembre de 2026.

• No se rompe nada: los IDs y las llamadas actuales siguen funcionando. El waba_id que ya tenías ahora identifica a la Messaging account.
• Varias Messaging accounts por número: cada proveedor puede facturar por separado sobre un mismo número; el límite de mensajería y el throughput se comparten.
• Tareas para desarrolladores: el campo messaging_account_id reemplaza a paid_messaging_account_id (migración antes del 31/12/2026), y en 2027 llegan IDs y webhooks propios de la WhatsApp account.
• Migración de números: en el modelo nuevo no está soportada; dentro de un mismo portfolio se vinculan o desvinculan WhatsApp accounts.

Calendario completo y qué hacer en cada fase: WhatsApp account y Messaging account.

Varias funciones de WhatsApp para empresas son parte de la Cloud API o funcionan sobre el mismo número. Esta tabla resume cómo se relaciona cada una.

Usar la Cloud API no tiene costo de licencia ni de alojamiento. Meta cobra por mensaje entregado, según la categoría del mensaje y el país del destinatario, y tu proveedor cobra aparte por su plataforma.

• Por mensaje entregado: desde el 1 de julio de 2025 Meta cobra cada mensaje entregado, no cada conversación. Las categorías son Marketing, Utility y Authentication (con plantilla), y Service y Meta Business Agent (sin plantilla).
• Servicio: desde el 1 de octubre de 2026, los primeros 1.000 mensajes de servicio por mes de cada número son gratis; después se cobran a la tarifa de Utility del país. Las reacciones no se cobran.
• Utility dentro de la ventana: desde el 1 de octubre de 2026 también se cobra.
• Free Entry Point (FEP): si un usuario te escribe desde un anuncio que hace clic a WhatsApp (en la app de Android o iOS) y respondes dentro de 24 horas, tu respuesta es gratis y durante hasta 7 días desde ella no se cobran Marketing, Utility, Authentication ni Service (Meta Business Agent sí). Es otro reloj: la ventana de 24 horas sigue definiendo cuándo puedes escribir texto libre, y fuera de ella necesitas plantillas aunque el FEP siga abierto (mientras dure, no se cobran).
• Descuentos por volumen: Utility y Authentication tienen tarifas escalonadas que se suman a nivel de business portfolio, aunque uses varios proveedores.
• Sin costo extra: la mejora a 1.000 mps no se cobra. Y para probar, el número de prueba envía plantillas sin método de pago cargado.
• Método de pago: se carga en la Messaging account, o lo cubre la línea de crédito de tu proveedor si es Solution Partner. Sin método de pago, Meta entrega los mensajes de servicio dentro del cupo gratis, pero no los que lo superan.

Esta es la ruta oficial de Meta para pasar de cero a un número en producción si integras por tu cuenta. Con un proveedor, los pasos 2 a 7 los resuelve Embedded Signup.

1. Prepara tu business portfolio en Meta Business Suite. Verificar la empresa no es obligatorio para probar, pero te sirve para escalar y para la OBA.
2. Crea la app en el App Dashboard de Meta for Developers con el caso de uso “Connect with customers through WhatsApp” y asóciala a tu portfolio.
3. Conecta una Messaging account en API Setup. Meta crea una WhatsApp account, una Messaging account y un número de prueba con límites relajados y sin método de pago.
4. Envía tu primer mensaje: genera un token temporal, elige el número de prueba y envía la plantilla hello_world a tu teléfono. Respóndela para abrir la ventana de 24 horas.
5. Configura el webhook: carga la Callback URL y el Verify token en la configuración de la app y suscríbete al campo messages.
6. Crea un usuario del sistema y genera un token de larga duración con los tres permisos de WhatsApp.
7. Suma tu número real: agrégalo, verifícalo y regístralo con el PIN. Carga un método de pago en la Messaging account.
8. Prepara tus plantillas y el nombre visible, y espera la aprobación de Meta.
9. Pasa la app a modo Live para recibir todos los webhooks.
10. Conecta tu operación: CRM, bandeja de agentes y un Agente IA que atienda y derive a una persona cuando haga falta.

La On-Premises API era la versión que la empresa o su proveedor instalaba y mantenía en servidores propios. Convivió con la Cloud API desde 2022 y dejó de funcionar el 23 de octubre de 2025. Esta sección reemplaza nuestra antigua comparativa entre ambas.

Meta justificó el cambio con estos argumentos: menos costo de instalación, alojamiento y mantenimiento; hasta 1.000 mensajes por segundo, cuatro veces lo que admitía On-Premises; 99,9 % de disponibilidad; cumplimiento de GDPR y LGPD y certificaciones SOC 2 y SOC 3; y la opción de almacenamiento local, para elegir en qué país se guardan los datos en reposo.