Actualizado el 25/10/2026
La WhatsApp Cloud API es la versión de la API oficial de WhatsApp alojada por la propia Meta: no instalas ningún servidor, solo haces llamadas HTTP a la Graph API (graph.facebook.com) y recibes eventos por webhook. Desde el 23 de octubre de 2025, con el fin de la On-Premises API, es la única forma de usar la WhatsApp Business Platform. Meta cobra por mensaje entregado, con un precio que depende de la categoría del mensaje y del país del destinatario.
Este artículo se centra en la parte técnica de la Cloud API: componentes, flujo de un mensaje, límites y costo. Si quieres la comparación con las bibliotecas no oficiales, lee API oficial vs. API no oficial de WhatsApp.
Qué es la WhatsApp Cloud API
Meta llama WhatsApp Business Platform al conjunto de APIs que permite a las empresas conversar con sus clientes en WhatsApp desde sus propios sistemas. La Cloud API es la parte de esa plataforma que envía y recibe mensajes, hace llamadas y administra grupos, según la descripción general de la Cloud API.
«Cloud» significa que la infraestructura de mensajería corre en Meta. Tu código no guarda sesión, no mantiene una conexión abierta con WhatsApp y no depende de un celular encendido. Solo:
- hace solicitudes HTTPS autenticadas con un token de acceso;
- recibe solicitudes de Meta en un endpoint de webhook.
Eso es distinto de las bibliotecas que emulan WhatsApp Web (Baileys, WPPConnect), que mantienen una sesión abierta tras escanear un código QR.
El fin de la On-Premises API
Hasta 2025 había dos formas oficiales de usar la plataforma: la Cloud API, alojada por Meta, y la On-Premises API, en la que la empresa (o su proveedor) alojaba un cliente en contenedores propios. Meta retiró la segunda por etapas, según la página de retiro de la On-Premises API:
| Fecha | Qué cambió |
|---|---|
| 9 de enero de 2024 | Las funciones nuevas pasaron a salir solo en la Cloud API; On-Premises recibía solo correcciones |
| 1 de julio de 2024 | Los números empresariales solo pueden registrarse para la Cloud API |
| 23 de octubre de 2025 | Expiró la última versión del cliente On-Premises; los mensajes de números aún registrados ahí dejaron de entregarse |
En la práctica, hoy «API oficial de WhatsApp», «WhatsApp Business API» y «Cloud API» se refieren al mismo producto. Los tutoriales antiguos que hablan de instalar un contenedor Docker de WhatsApp están desactualizados.
Componentes de la plataforma
La documentación de Meta divide la plataforma en algunas piezas. Cada una aparece en endpoints y permisos distintos:
| Componente | Para qué sirve |
|---|---|
| Cloud API | Enviar y recibir mensajes, hacer llamadas y administrar grupos |
| Business Management API | Administrar cuentas de mensajería (WABA), números, plantillas, facturación y métricas |
| Marketing Messages API | Enviar mensajes de marketing optimizados, con métricas de entrega y conversión |
| Webhooks | Avisar a tu servidor sobre mensajes recibidos y cambios de estado, en JSON |
| Meta Business Agent | Configurar agentes de IA de la propia Meta que responden conversaciones |
Y algunos objetos que usarás todo el tiempo:
- Portafolio comercial (antes Business Manager): la cuenta de la empresa en Meta.
- Cuenta de mensajería (WABA,
waba_id): agrupa números y plantillas. - Número de teléfono empresarial (
phone_number_id): este ID va en la URL de envío. - App de Meta: la app creada en el panel de desarrolladores, vinculada al portafolio, que recibe permisos y webhooks.
- Token de acceso: en producción, un token de usuario del sistema con los permisos
whatsapp_business_messaging,whatsapp_business_managementybusiness_management. Detalles en token permanente con usuario del sistema.
Cómo funciona el envío de un mensaje
El envío es un POST a /{phone_number_id}/messages. El ejemplo envía una plantilla a un número de Brasil directo a la Graph API (cambia la versión por la actual indicada en el changelog de Meta):
curl -X POST "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/messages" \
-H "Authorization: Bearer TOKEN_DE_USUARIO_DEL_SISTEMA" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "5511999999999",
"type": "template",
"template": {
"name": "confirmacion_pedido",
"language": { "code": "es" },
"components": [
{ "type": "body", "parameters": [ { "type": "text", "text": "María" } ] }
]
}
}'La respuesta trae el wa_id del destinatario y el identificador del mensaje (wamid):
{
"messaging_product": "whatsapp",
"contacts": [{ "input": "5511999999999", "wa_id": "5511999999999" }],
"messages": [{ "id": "wamid.HBgLNTUxMTk5OTk5OTk5..." }]
}Esa respuesta solo confirma que Meta aceptó el mensaje. La entrega, la lectura y los fallos llegan después por webhook, como explicamos en estados de mensaje por webhook. Hay más ejemplos de envío en cURL, Node.js y Python en cómo enviar un mensaje con la API de WhatsApp.
Dos reglas que cambian tu código
- Ventana de atención de 24 horas. Cuando el cliente te escribe, puedes responder con mensajes libres durante 24 horas. Fuera de esa ventana, solo plantillas aprobadas.
- Plantillas con categoría. Marketing, utilidad o autenticación. La categoría define el precio y Meta la revisa.
Cómo funciona la recepción: webhooks
Cuando un cliente responde, Meta hace un POST a tu endpoint con el objeto whatsapp_business_account. Los mensajes y los estados vienen dentro de entry[].changes[].value:
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WABA_ID",
"changes": [{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": { "phone_number_id": "PHONE_NUMBER_ID" },
"contacts": [{ "wa_id": "5511999999999", "profile": { "name": "María" } }],
"messages": [{
"from": "5511999999999",
"id": "wamid.HBgL...",
"timestamp": "1761400000",
"type": "text",
"text": { "body": "Quiero saber dónde está mi pedido" }
}]
}
}]
}]
}Tu servidor debe responder rápido con 200, validar la firma del payload y procesar el evento en una cola.
Límites de la Cloud API
| Límite | Valor | Fuente |
|---|---|---|
| Throughput por número | Hasta 80 mensajes por segundo por defecto | Throughput |
| Throughput ampliado | 1.000 mps, automático para números elegibles (límite ilimitado, 100 mil usuarios únicos en 24 h, calidad amarilla o mejor) | Throughput |
| Números en coexistencia | 20 mps fijos | Throughput |
| Límite de mensajes | 250 destinatarios únicos en 24 h fuera de la ventana para portafolios nuevos; luego 2.000, 10.000, 100.000 e ilimitado | Límites de mensajes |
| Números por portafolio | 2 al inicio; 20 tras verificar la empresa o al llegar al límite de 2.000 | Números de teléfono |
Si superas el throughput recibes el error 130429 hasta que la tasa vuelva a lo permitido. El límite de mensajes se calcula por portafolio y lo comparten todos sus números.
Cuánto cuesta la WhatsApp Cloud API
Meta no cobra mensualidad ni hospedaje. El costo es por mensaje entregado, según la página de precios:
- solo se cobran los mensajes de la empresa al usuario; lo que envía el cliente es gratis;
- el precio depende de la categoría (marketing, utilidad, autenticación, servicio) y del país del destinatario;
- cada número tiene 1.000 mensajes de servicio gratis al mes;
- los mensajes dentro de la ventana de punto de entrada gratuito, abierta por anuncios de clic a WhatsApp, no se cobran (salvo los de Meta Business Agent);
- Meta solo cambia precios el primer día de cada trimestre.
Como ejemplo, estas son las tarifas en reales brasileños (BRL) para destinatarios en Brasil, vigentes desde el 1 de octubre de 2026:
| Categoría | Precio por mensaje entregado |
|---|---|
| Marketing | R$ 0,3217 |
| Utilidad | R$ 0,0350 |
| Autenticación | R$ 0,0350 |
| Servicio (después de 1.000 por número al mes) | R$ 0,0350 |
Las tarifas de otros países están en las tablas de Meta de esa misma página. Desde el 1 de octubre de 2026, los mensajes de utilidad dentro de la ventana de atención también se cobran, y las cuentas sin método de pago dejan de recibir la entrega de mensajes de servicio cuando se agota el nivel gratuito. Si quieres saber qué puedes hacer sin pagar, lee ¿existe una API de WhatsApp gratis?.
A eso se suma el costo de operar la integración: tu propio equipo, si integras directo, o el proveedor que elijas.
Integrar directo o usar un proveedor
Puedes integrar directo con la Cloud API: crear la app, generar el token de usuario del sistema, configurar el webhook, registrar un método de pago en la cuenta de mensajería y mantener todo eso en producción. Un proveedor te quita parte de ese trabajo; los criterios para elegirlo están en cómo elegir un proveedor de API de WhatsApp.
WhatsApp Cloud API con Vectalk
Vectalk es un proxy de la WhatsApp Cloud API: tu aplicación llama a Vectalk, que reenvía la llamada a Meta. Los payloads son los mismos de Meta; solo cambian la URL base y el token.
| Cloud API directa | Vectalk | |
|---|---|---|
| URL base | https://graph.facebook.com/vXX.X | https://apis.vectalk.com.br/api |
| Token | Usuario del sistema de Meta | Token generado en el panel de Vectalk |
| Webhooks | Formato de Meta, un endpoint por app | Formato de Meta, varias URLs por instancia |
| Pago a Meta | Método de pago en la cuenta de mensajería | Tú pagas a Vectalk y Vectalk paga a Meta |
Vectalk también ofrece coexistencia: el número sigue en la app WhatsApp Business y además funciona en la API. Para empezar, crea tu cuenta en apps.vectalk.com.br/register y sigue la guía rápida (documentación en portugués).
Preguntas frecuentes
¿La Cloud API y la WhatsApp Business API son lo mismo?
Hoy, sí. «WhatsApp Business API» era el nombre general cuando existían dos versiones. Desde el fin de la On-Premises API, el 23 de octubre de 2025, la Cloud API es la única forma oficial de usar la plataforma.
¿Necesito un servidor para usar la Cloud API?
No para alojar WhatsApp, que corre en Meta. Solo necesitas un endpoint HTTPS público para recibir los webhooks, que puede ser una función serverless o un servidor común.
¿La WhatsApp Cloud API es gratis?
Meta no cobra mensualidad, pero los mensajes se cobran al entregarse, según categoría y país. Hay 1.000 mensajes de servicio gratis por número al mes y ventanas sin cobro para conversaciones que llegan desde anuncios.
¿Qué versión de la Graph API debo usar?
La más reciente que aparece en el changelog de Meta. Cada versión tiene fecha de retiro, así que guarda la versión como configuración y no la dejes fija en el código.
¿Puedo usar el número que ya tengo en el celular?
Si está en la app WhatsApp Business, sí, mediante la coexistencia. Si está en WhatsApp normal, hay que eliminar la cuenta de la app antes de registrar el número.
Fuentes oficiales consultadas el 25/10/2026: Descripción general de la Cloud API, Retiro de la On-Premises API, Primeros pasos, Throughput, Límites de mensajes, Números de teléfono, Precios, Documentación de Vectalk.