WhatsApp Cloud API: qué es y cómo integrarla (número, token, webhook y primer envío)

Qué es la WhatsApp Cloud API

La Cloud API es la parte de la WhatsApp Business Platform que envía y recibe mensajes desde un sistema, no desde un móvil. Usa la Graph API de Meta para enviar y webhooks para avisar de lo que llega y de qué pasó con cada mensaje. Quien habla de la “API de WhatsApp” o de la API oficial de WhatsApp habla de ella.

Existía una versión instalada en los servidores de la propia empresa, la On-Premises API, pero Meta llevó toda la plataforma a la nube. La página de retirada dice que, desde el 1 de julio de 2024, los números nuevos solo se registran en la Cloud API, y que la última versión de On-Premises, la v2.63, caducó el 23 de octubre de 2025.

La diferencia con la app WhatsApp Business es que la API no tiene pantalla: es un conjunto de endpoints, y la conversación aparece donde tu sistema la muestre. A cambio, abre lo que la app no tiene: agentes sin límite de dispositivos, automatización, integración con tienda y CRM y mensajes interactivos, como botones, listas y los formularios de WhatsApp Flows.

Qué tiene que existir antes del código

La guía de inicio de Meta pide una cuenta de desarrollador, una app en Meta for Developers con el caso de uso “Connect with customers through WhatsApp”, un portfolio empresarial y una cuenta de WhatsApp Business. El panel crea solo una cuenta y un número de prueba, con límites holgados y envío de plantillas sin método de pago.

En 2026 la cuenta cambió. Desde el 23 de septiembre, el nuevo modelo la divide en dos: la cuenta de WhatsApp, con el número y el nombre visible, y la cuenta de mensajería, con plantillas, facturación y webhooks. El ID antiguo pasa a ser el de mensajería y nada se rompe ahora. En el primer semestre de 2028, las rutas de la API cambian el ID del número por el de la cuenta de WhatsApp; guarda los dos desde ya.

El número debe ser tuyo, con código de país y de área, y recibir un código por SMS o llamada; los cortos no valen. Si ya está en WhatsApp, hay que borrar esa cuenta antes. La excepción es la coexistencia con la app WhatsApp Business, que mantiene el número en el móvil y en la API, pero entra por el registro de un partner o proveedor de tecnología de Meta, no por la integración directa.

La verificación de la empresa no es obligatoria para empezar, pero cambia los techos: con el portfolio verificado, el límite de números pasa de 2 a 20, el de mensajes de 250 a 2.000 personas al día, y el de plantillas, de 250 a hasta 6.000 cuando un número ya tiene el nombre visible aprobado.

Token permanente y registro del número

El botón “Generate access token” del panel genera un token de usuario que, según la documentación, caduca cada pocas horas: vale para probar. En producción, el token es de un usuario del sistema, creado en la configuración del portfolio con acceso a la app y a las cuentas de WhatsApp, de larga duración y con tres permisos: business_management, whatsapp_business_management y whatsapp_business_messaging.

whatsapp_business_messaging cubre el envío y el webhook de mensajes; whatsapp_business_management, números, plantillas y los demás campos. Quien integra sus propios datos concede los dos al generar el token; la revisión de Meta para el acceso avanzado se exige a los partners. El token va en un almacén de secretos del servidor, nunca en el front-end ni en el repositorio; caducado, da error 190.

Añadir y verificar el número en WhatsApp Manager no basta: el registro solo se hace por la API, con POST /<PHONE_NUMBER_ID>/register, messaging_product: "whatsapp" y un pin de seis dígitos, el de la verificación en dos pasos (el actual, si existe, o uno nuevo). Son 10 solicitudes por número cada 72 horas; si te pasas, error 133016 y 72 horas de bloqueo.

El parámetro opcional data_localization_region activa el almacenamiento local, y la lista incluye Brasil (BR): una vez procesado, el contenido de los mensajes queda solo en centros de datos del país elegido. Cambiarlo exige cancelar el registro y registrar de nuevo. Y cada cambio aprobado del nombre visible exige un nuevo registro en 14 días.

El primer envío

La llamada es POST https://graph.facebook.com/v26.0/<PHONE_NUMBER_ID>/messages, con el token en Authorization: Bearer. El cuerpo lleva messaging_product: "whatsapp", recipient_type: "individual", el número en to, el type y un objeto con el nombre del tipo, como text. La v26.0, del 29 de julio de 2026, es la más reciente.

Fija la versión en la configuración y cámbiala a propósito. La guía de inicio de Meta todavía muestra la v23.0, disponible hasta el 8 de octubre de 2027; cada versión caduca según la tabla de la Graph API, y quien copia el ejemplo queda en una versión con plazo sin saberlo.

El texto libre solo sale dentro de la ventana de atención al cliente, que según la documentación se abre cuando el cliente escribe o llama, dura 24 horas y se reinicia con cada nuevo mensaje suyo. Fuera de ella, solo plantillas aprobadas: type: "template", con name, language.code y los components de las variables. Detalles en el post sobre la ventana de 24 horas de WhatsApp.

La respuesta trae contacts, con el número en input y el wa_id, que puede ser distinto, y messages[0].id, el wamid. Meta avisa de que solo confirma que la API aceptó la petición, no la entrega, y de que el orden de entrega puede no seguir el de las llamadas. Guarda el wamid antes que nada: une el envío con los estados del webhook.

Webhook: verificación, firma y suscripción

Al registrar la URL del webhook en el panel, Meta envía un GET con hub.mode=subscribe, hub.verify_token y hub.challenge. Si el verify_token coincide con la cadena que elegiste, responde 200 con el valor de hub.challenge en el cuerpo; cualquier otra respuesta deja el endpoint sin verificar y sin webhooks. El certificado TLS debe ser válido: no se aceptan los autofirmados.

Cada POST trae la cabecera X-Hub-Signature-256, con el formato sha256=<hash>: un HMAC-SHA256 del cuerpo con el app secret como clave. Calcúlalo sobre los bytes en bruto de la petición, antes de parsear el JSON, compara en tiempo constante y descarta lo que no coincida. Meta también admite mTLS y lo recomienda frente a una lista de IP, porque sus direcciones cambian.

En el panel, suscríbete al campo messages: trae los mensajes de los clientes y los estados de los que enviaste. Suscribe la app a cada cuenta con POST /<WABA_ID>/subscribed_apps, una por una, como pide la documentación. Y pasa la app al modo Live: Meta avisa de que algunos webhooks no se envían en modo de desarrollo.

Webhook en producción: 200 rápido, cola e idempotencia

Si el endpoint responde algo distinto de 200, o la entrega falla, Meta reintenta, cada vez más espaciado, hasta 7 días, y la documentación avisa de que eso genera duplicados que tu servidor debe descartar. Un payload ocupa hasta 3 MB y puede agrupar hasta 1.000 actualizaciones. No hay API para recuperar webhooks antiguos: lo que no se guardó se pierde.

El diseño correcto: el handler comprueba la firma, guarda el payload en bruto en una cola o tabla duradera y responde 200. Actualizar la conversación, descargar archivos o llamar al CRM y al agente de IA queda para un worker. Un handler lento arriesga reenvíos y mensajes procesados dos veces.

Idempotencia por ID: un mensaje recibido tiene clave única en messages[].id, y un estado, en el wamid más el estado. Y no cuentes con el orden: cuando el cliente lee al momento, el delivered ni se envía, y un reenvío puede traer un estado antiguo tras uno nuevo. Trata el estado como escalera, sent, delivered, read, que nunca baja; el failed llega con errors.

Desde abril de 2026 los webhooks traen el BSUID, un ID del cliente por portfolio, en campos como contacts[].user_id. Si el cliente usa un nombre de usuario, puede faltar el teléfono, y Meta recomienda no contar con wa_id ni from. Desde julio se puede enviar al BSUID, en el campo recipient. Modela el contacto con las dos claves.

Multimedia, límites y los errores más comunes

Para enviar un archivo, súbelo con POST /<PHONE_NUMBER_ID>/media y usa el ID que vuelve, que Meta recomienda en lugar de un enlace; se guarda 30 días. Las imágenes son JPEG o PNG de 8 bits, en RGB o RGBA, de hasta 5 MB: un JPEG en CMYK de imprenta no pasa.

A la llegada, el webhook trae el ID del archivo, no el archivo. GET /<MEDIA_ID> devuelve una URL que caduca en 5 minutos, la descarga exige el token, y el ID recibido solo dura 7 días. Copia el archivo a tu almacenamiento en cuanto llegue el mensaje.

Hay dos techos. El rendimiento: cada número envía hasta 80 mensajes por segundo y sube solo a 1.000 con el portfolio ilimitado, 100.000 personas fuera de la ventana en 24 horas y calidad amarilla o mejor; en coexistencia, se queda en 20. Y el límite de mensajes, que cuenta personas fuera de la ventana en 24 horas en todo el portfolio y sube de 2.000 a 10.000, 100.000 e ilimitado con calidad alta y la mitad del techo usada en 7 días.

Los errores comunes caben en tres grupos. Los que piden esperar y reintentar con intervalos crecientes: 130429, de rendimiento, y 131056, demasiados mensajes a la misma persona. Los que piden otro mensaje: 131047, ventana cerrada, y 132001, plantilla inexistente en ese idioma. Y los que piden a una persona: 190, token caducado; 133010, número sin registrar; 131042, pago; y 131048, número restringido por spam. Más detalle sobre los errores de la Cloud API.

Integrar directamente o con un partner de Meta

Integrar directamente da control total y te deja lo que la API no hace: la cola que respeta el rendimiento, los reintentos, el almacenamiento de webhooks, la copia de archivos, el cálculo de la ventana por contacto y los cambios de versión. Y los cambios de Meta: anunció que, después del 13 de octubre de 2027, el marketing por la Cloud API da error y pasa a la Marketing Messages API.

La API tampoco tiene inbox: repartir conversaciones, mostrar el historial, avisar a quien atiende y darle un panel al responsable es software que construir y mantener. La factura de Meta es igual en ambos caminos: por mensaje entregado, por categoría y país, incluidos, desde el 1 de octubre de 2026, los de servicio por encima de 1.000 por número al mes.

La plataforma de un Meta Business Partner entrega esas piezas listas: conecta el número por el registro de Meta, ofrece la coexistencia y le da el inbox al equipo. Integras con su API y su webhook, como en esta documentación de la API de mensajería para WhatsApp, y el número sigue en tu cuenta de WhatsApp. Si WhatsApp es el centro de tu producto y tienes ingeniería para mantenerlo, ve directo; si es un canal de la operación, plataforma.