Arquitectura de la API: Cloud vs On-Premise

La WhatsApp Business API es la puerta de entrada para integrar WhatsApp en aplicaciones empresariales a escala. A diferencia de la app WhatsApp Business gratuita (pensada para negocios pequeños), la API permite enviar mensajes programáticamente, automatizar conversaciones y procesar miles de interacciones simultáneas. Si estás construyendo un agente inteligente por WhatsApp o cualquier sistema de comunicación automatizada, esta es la infraestructura que necesitas dominar.

Meta ofrece dos modelos de despliegue para la WhatsApp Business API, y la elección entre ellos impacta directamente tu arquitectura, costos y capacidad de mantenimiento.

Cloud API (recomendada)

La Cloud API es alojada y mantenida directamente por Meta. No necesitas levantar servidores propios ni gestionar contenedores Docker. Te conectas a los endpoints REST de Meta y listo. Esta es la opción que Meta recomienda activamente y donde concentra sus esfuerzos de desarrollo.

Las ventajas son significativas: cero infraestructura que mantener, actualizaciones automáticas de funcionalidades y seguridad, menor latencia en muchas regiones, soporte nativo para todas las features nuevas desde el día uno, y un proceso de onboarding que puede completarse en minutos en lugar de días. El endpoint base es https://graph.facebook.com/v21.0/ y todas las operaciones se realizan con llamadas HTTP estándar.

La Cloud API también ofrece mayor throughput por defecto: hasta 80 mensajes por segundo por número de teléfono y 200 requests por segundo por app. Para la mayoría de las empresas en Chile y Latinoamérica, estos límites son más que suficientes.

On-Premise API

La On-Premise API (también llamada "API local") requiere que instales y mantengas tus propios servidores usando contenedores Docker. Tú controlas la infraestructura completa: la base de datos (PostgreSQL o MySQL), los contenedores de la aplicación (webapp y coreapp), y toda la configuración de red.

Esta opción tiene sentido en escenarios muy específicos: empresas con requisitos regulatorios estrictos que exigen que los datos no salgan de su infraestructura, organizaciones con políticas de seguridad que prohíben depender de servicios cloud de terceros, o casos donde necesitas control absoluto sobre el entorno de ejecución. Sin embargo, Meta ha señalado que la On-Premise API recibirá menos inversión en nuevas funcionalidades comparada con Cloud API.

Para la gran mayoría de desarrolladores y empresas, Cloud API es la elección correcta. El resto de esta guía se centra en Cloud API, señalando diferencias con On-Premise solo cuando son relevantes.

Autenticación y tokens de acceso

Antes de enviar tu primer mensaje, necesitas configurar correctamente la autenticación. La WhatsApp Cloud API usa el sistema de autenticación de Meta (Graph API), basado en tokens de acceso OAuth 2.0.

Token temporal vs token permanente

Cuando creas tu app en Meta for Developers, obtienes un token temporal que dura 24 horas. Este token es útil para pruebas rápidas, pero no sirve para producción. Para un entorno productivo necesitas generar un System User Token que no expira (o tiene una expiración configurable de hasta 60 días).

El flujo para obtener un token permanente es:

  1. Ir a Meta Business Suite > Configuración del negocio > Usuarios del sistema
  2. Crear un usuario del sistema con rol de administrador
  3. Asignarle los assets necesarios (tu WhatsApp Business Account y la app)
  4. Generar un token con los permisos whatsapp_business_management y whatsapp_business_messaging

Seguridad del token

El token de acceso es la llave maestra de tu integración. Si alguien obtiene tu token, puede enviar mensajes desde tu número, leer conversaciones y modificar configuraciones. Las mejores prácticas incluyen:

Cada request a la API debe incluir el token en el header Authorization: Bearer {token}. Todas las comunicaciones son sobre HTTPS, así que el token viaja encriptado en tránsito.

Webhooks: configuración, eventos y verificación

Los webhooks son el mecanismo mediante el cual Meta te notifica en tiempo real sobre eventos que ocurren en tu cuenta: mensajes entrantes, cambios de estado de mensajes, actualizaciones de cuenta y más. Sin webhooks configurados, tu aplicación no puede recibir mensajes ni saber si los mensajes enviados fueron entregados o leídos.

Configuración del endpoint

Tu servidor necesita exponer un endpoint HTTPS público que Meta pueda alcanzar. Este endpoint debe manejar dos tipos de requests:

El endpoint debe responder en menos de 5 segundos. Si tu procesamiento toma más tiempo, responde con un 200 inmediatamente y procesa el evento de forma asíncrona en una cola (SQS, Redis, RabbitMQ). Si Meta no recibe respuesta en 5 segundos, reintentará el envío con backoff exponencial, y si falla consistentemente, desactivará tu webhook.

Verificación del webhook

Cuando configuras el webhook en Meta for Developers, Meta envía un request GET con tres parámetros: hub.mode (siempre "subscribe"), hub.challenge (un string aleatorio) y hub.verify_token (un string que tú definiste). Tu endpoint debe verificar que el verify_token coincide con el que configuraste y responder con el valor de hub.challenge.

// Ejemplo de verificación en Node.js
app.get('/webhook', (req, res) => {
  const mode = req.query['hub.mode'];
  const token = req.query['hub.verify_token'];
  const challenge = req.query['hub.challenge'];

  if (mode === 'subscribe' && token === VERIFY_TOKEN) {
    res.status(200).send(challenge);
  } else {
    res.sendStatus(403);
  }
});

Eventos principales

Los eventos que recibirás por webhook se agrupan en el campo entry[].changes[].field. Los más importantes son:

Validación de firma

Cada request POST que Meta envía a tu webhook incluye un header X-Hub-Signature-256 con un HMAC SHA-256 del payload, firmado con tu App Secret. Siempre debes validar esta firma antes de procesar el evento para evitar que un atacante inyecte eventos falsos en tu sistema. Si estás construyendo un agente inteligente, esta validación es crítica para la seguridad de tus usuarios.

// Validación de firma en Node.js
const crypto = require('crypto');

function verifySignature(payload, signature, appSecret) {
  const expectedSig = crypto
    .createHmac('sha256', appSecret)
    .update(payload)
    .digest('hex');
  return `sha256=${expectedSig}` === signature;
}

Templates de mensajes: tipos, aprobación y variables

Los templates (o plantillas) son mensajes pre-aprobados por Meta que puedes enviar a usuarios fuera de la ventana de 24 horas. Son la única forma de iniciar conversaciones proactivamente y son fundamentales para campañas de marketing, notificaciones transaccionales y flujos de re-engagement.

Categorías de templates

Meta clasifica los templates en tres categorías, cada una con precios y políticas de aprobación diferentes:

Estructura de un template

Un template puede incluir los siguientes componentes:

Variables dinámicas

Las variables permiten personalizar cada mensaje enviado. Al crear el template defines placeholders como {{1}}, {{2}}, etc., y al enviar el mensaje proporcionas los valores reales. Por ejemplo, un template de confirmación de pedido podría ser:

Hola {{1}}, tu pedido #{{2}} ha sido confirmado. El monto total es ${{3}} y será entregado el {{4}}. Gracias por tu compra.

Las variables tienen restricciones: no pueden contener saltos de línea, no pueden ser el único contenido del body, y deben tener valores de ejemplo al momento de enviar el template a aprobación.

Proceso de aprobación

Cada template debe ser aprobado por Meta antes de poder usarse. El proceso típico:

  1. Creas el template via API (POST /{WABA_ID}/message_templates) o desde el Business Manager
  2. Meta revisa el template (automática y/o manualmente). La mayoría se aprueba en menos de 1 hora
  3. Recibes una notificación via webhook (message_template_status_update) con el resultado: APPROVED, REJECTED o PAUSED

Si un template es rechazado, puedes editarlo y reenviarlo. Los motivos de rechazo más comunes son: contenido que viola las políticas de comercio de Meta, templates demasiado genéricos sin valor claro para el usuario, o variables de ejemplo que no coinciden con el uso real.

Sesiones y la ventana de 24 horas

Uno de los conceptos más importantes (y más confusos para desarrolladores nuevos) es el modelo de sesiones y ventanas de conversación de WhatsApp. Entender cómo funcionan es esencial para diseñar flujos correctos y controlar costos.

Cómo funciona la ventana

Cuando un usuario te envía un mensaje, se abre una ventana de servicio de 24 horas. Durante estas 24 horas, puedes responder con mensajes de texto libre (sin usar templates). Cada nuevo mensaje del usuario reinicia el contador de 24 horas. Si el usuario no envía un nuevo mensaje y las 24 horas expiran, solo puedes contactarlo usando templates pre-aprobados.

Este modelo existe para proteger a los usuarios de spam. Meta quiere asegurar que las empresas no bombardeen a los usuarios con mensajes no solicitados. En la práctica, esto significa que tu arquitectura debe rastrear el estado de la ventana para cada conversación activa.

Tipos de conversaciones y pricing

Meta cobra por conversación, no por mensaje individual. Una conversación es un período de 24 horas que se abre cuando envías un mensaje. Los tipos son:

Un punto crítico: si un usuario te envía un mensaje y tú respondes con un template de marketing (en lugar de texto libre), se abrirán dos conversaciones: una de servicio y una de marketing. Esto duplica el costo. La mejor práctica es responder con texto libre dentro de la ventana y reservar los templates para comunicaciones proactivas fuera de la ventana.

Gestión de ventanas en tu backend

Tu sistema necesita trackear el timestamp del último mensaje de cada usuario para saber si la ventana está abierta o cerrada. Una implementación típica incluye:

Si estás desarrollando una solución a medida, este manejo de ventanas debe ser una pieza central de tu arquitectura desde el diseño inicial.

Envío de media: imágenes, documentos y audio

La API soporta el envío y recepción de múltiples tipos de media. Los mensajes con media tienen tasas de engagement significativamente más altas que los mensajes de solo texto, especialmente en contextos de marketing y soporte.

Tipos de media soportados

Dos métodos para enviar media

Puedes enviar media de dos formas:

1. Por URL: proporcionas una URL pública donde está alojado el archivo. Meta descarga el archivo desde tu servidor al momento de enviar el mensaje. La URL debe ser accesible públicamente (sin autenticación) y servir los headers de Content-Type correctos.

// Envío de imagen por URL
POST https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/messages
{
  "messaging_product": "whatsapp",
  "to": "56912345678",
  "type": "image",
  "image": {
    "link": "https://tu-servidor.com/imagen.jpg",
    "caption": "Cotización actualizada"
  }
}

2. Por Media ID: primero subes el archivo a los servidores de Meta y obtienes un Media ID. Luego usas ese ID para enviar el mensaje. El archivo se almacena en los servidores de Meta por 30 días. Este método es más confiable porque no depende de la disponibilidad de tu servidor en el momento del envío.

// Paso 1: Subir el archivo
POST https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/media
Content-Type: multipart/form-data
  messaging_product: whatsapp
  file: @documento.pdf
  type: application/pdf

// Respuesta: { "id": "media_id_123" }

// Paso 2: Enviar usando el Media ID
POST https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/messages
{
  "messaging_product": "whatsapp",
  "to": "56912345678",
  "type": "document",
  "document": {
    "id": "media_id_123",
    "filename": "cotizacion-abril-2026.pdf"
  }
}

Recepción de media

Cuando un usuario envía media, el webhook incluye un media_id pero no el archivo en sí. Debes hacer un request GET a /{media_id} para obtener la URL de descarga temporal, y luego descargar el archivo desde esa URL. Las URLs de descarga expiran, así que descarga el archivo inmediatamente y almacénalo en tu infraestructura (S3, GCS, etc.).

Catálogos y commerce

La WhatsApp Business API incluye funcionalidades de comercio electrónico que permiten a las empresas mostrar productos directamente en WhatsApp sin necesidad de que el usuario salga de la app. Esto es especialmente poderoso para empresas de retail, restaurantes y servicios que operan en Chile.

Configuración del catálogo

Los catálogos se gestionan a través del Commerce Manager de Meta. Puedes subir productos manualmente o sincronizarlos automáticamente desde tu ecommerce mediante un feed de datos (CSV, XML o integración directa con plataformas como Shopify). Cada producto incluye: nombre, descripción, precio, URL de imagen, SKU y disponibilidad.

Una vez configurado el catálogo en Commerce Manager, lo vinculas a tu número de WhatsApp Business. A partir de ahí, puedes enviar mensajes con productos específicos o con secciones completas del catálogo.

Mensajes de producto único

Permiten destacar un producto específico con imagen, nombre, precio y un botón "Ver producto". El usuario puede ver los detalles y agregar el producto a su carrito sin salir de WhatsApp. Este tipo de mensaje es ideal para recomendaciones personalizadas basadas en el historial de compra o las preferencias del cliente.

Mensajes de lista de productos

Permiten enviar hasta 30 productos organizados en secciones. El usuario ve un botón "Ver artículos" que abre una interfaz tipo catálogo dentro de WhatsApp. Puede navegar por las secciones, ver detalles de cada producto y agregar múltiples items a su carrito. Este formato funciona especialmente bien para menús de restaurantes, catálogos de temporada o selecciones curadas.

Flujo de compra

Cuando el usuario selecciona productos y "envía" su carrito, tu webhook recibe un evento de tipo order con la lista de productos seleccionados, cantidades y el texto que el usuario haya agregado. A partir de ahí, tu sistema puede confirmar la orden, calcular el total con envío, y guiar al usuario hacia el pago. Si tienes un equipo de desarrollo trabajando en la integración, este flujo de commerce puede reducir significativamente la fricción de compra comparado con redirigir al usuario a un sitio web externo.

Rate limits y buenas prácticas de envío

Entender los rate limits de la WhatsApp API es crucial para evitar errores, bloqueos y degradación de la calidad de tu número. Meta implementa múltiples capas de limitación que debes respetar.

Tiers de mensajería

Tu capacidad de envío está determinada por el tier de tu número de teléfono. Los tiers se asignan automáticamente según tu volumen y calidad:

Para subir de tier, necesitas enviar al menos el 50% de tu capacidad actual durante un período de 7 días consecutivos, manteniendo una calificación de calidad "Alta" o "Media". Si tu calidad baja a "Baja", Meta puede reducir tu tier o restringir tu número.

Rate limits de la API

Más allá de los tiers de conversaciones, la API tiene límites de llamadas:

Calidad del número

Meta monitorea la calidad de tu número de teléfono basándose en señales de los usuarios: reportes de spam, bloqueos y tasas de lectura. La calidad se clasifica en Verde (Alta), Amarillo (Media) y Rojo (Baja). Si caes a calidad Baja, Meta puede:

Buenas prácticas para mantener alta calidad

Si necesitas enviar campañas masivas a miles de contactos, considera usar un servicio profesional como los agentes de WhatsApp Business API que ya tienen la infraestructura optimizada para alto volumen con alta calidad.

Monitoreo y debugging

Cuando algo falla en tu integración con WhatsApp (y algo va a fallar), necesitas las herramientas adecuadas para diagnosticar y resolver problemas rápidamente. La API ofrece varias vías de monitoreo que todo desarrollador debe conocer.

Códigos de error comunes

La API retorna errores con códigos numéricos y mensajes descriptivos. Los más frecuentes son:

Logs y trazabilidad

Cada mensaje enviado recibe un wamid (WhatsApp Message ID) que debes almacenar en tu base de datos. Este ID te permite rastrear el ciclo de vida completo del mensaje a través de los status webhooks: sent > delivered > read (o failed). Implementa un sistema de logging que registre:

Dashboard de Meta Business

Meta proporciona un dashboard en el Business Manager con métricas agregadas: mensajes enviados/entregados/leídos, calidad del número, estado de templates, y costos. Revisa este dashboard diariamente durante las primeras semanas de tu integración y semanalmente una vez estabilizada.

Health checks y alertas

Tu sistema de monitoreo debería incluir alertas para:

Para proyectos complejos, herramientas como Datadog, New Relic o Grafana con Prometheus son ideales para visualizar métricas de tu integración en tiempo real. Si no tienes la infraestructura de monitoreo, solicita un diagnóstico gratuito y te ayudamos a diseñar la arquitectura de observabilidad adecuada para tu caso.

Preguntas frecuentes sobre la WhatsApp Business API

¿Cuál es la diferencia entre WhatsApp Cloud API y On-Premise API?
La Cloud API es alojada por Meta y no requiere infraestructura propia: te conectas directamente a los servidores de Meta mediante endpoints REST. La On-Premise API requiere que instales y mantengas tus propios servidores con Docker. La Cloud API es más rápida de implementar, tiene actualizaciones automáticas y menor costo operativo, mientras que On-Premise ofrece mayor control sobre los datos pero con más complejidad de mantenimiento. Meta recomienda Cloud API para nuevas integraciones.
¿Cuánto cuesta usar la WhatsApp Business API?
Meta cobra por conversación, no por mensaje individual. Los precios varían según la categoría: marketing es la más cara, seguida de autenticación y utility. Las conversaciones de servicio (iniciadas por el usuario) son gratuitas las primeras 1,000 al mes. Los precios exactos dependen del país y se actualizan periódicamente en la documentación oficial de Meta. No hay costo fijo por tener la API activa.
¿Cuánto demora la aprobación de un template de WhatsApp?
La aprobación de templates típicamente toma entre 1 minuto y 24 horas. La mayoría se aprueba en menos de 1 hora si cumplen las políticas de Meta. Los templates con contenido financiero, de salud o político pueden tardar más. Si un template es rechazado, puedes editarlo y reenviarlo. Es recomendable tener templates aprobados con anticipación antes de lanzar campañas.
¿Qué pasa si envío un mensaje fuera de la ventana de 24 horas?
Si la ventana de 24 horas ha expirado, solo puedes enviar mensajes usando templates pre-aprobados por Meta. No puedes enviar mensajes de texto libre. Si intentas enviar un mensaje de texto libre fuera de la ventana, la API retornará el error 131047. Los templates permiten iniciar nuevas conversaciones, pero deben estar aprobados previamente y corresponder a una de las categorías permitidas (marketing, utility o authentication).
¿Cuáles son los rate limits de la WhatsApp Business API?
Los rate limits dependen de tu tier de mensajería. Un número nuevo comienza en Tier 1 (1,000 conversaciones únicas en 24 horas). A medida que mantienes buena calidad, puedes escalar a Tier 2 (10,000), Tier 3 (100,000) y Tier 4 (ilimitado). Para la Cloud API, el rate limit de llamadas es de 80 mensajes por segundo por número de teléfono y 200 solicitudes por segundo por app. Los media uploads están limitados a 100 por hora por app.
¿Necesito un BSP o puedo conectarme directo a la API de Meta?
Puedes conectarte directamente a la Cloud API de Meta sin un BSP (Business Solution Provider). Solo necesitas una cuenta de Meta Business, crear una app en Meta for Developers, verificar tu negocio y registrar un número de teléfono. Sin embargo, un BSP puede ser útil si necesitas soporte técnico dedicado, herramientas adicionales de gestión, o si prefieres no manejar la infraestructura de webhooks y tokens tú mismo. La conexión directa te da más control y evita costos intermediarios.
Siguiente paso

¿Necesitas integrar WhatsApp en tu negocio?

Te ayudamos a diseñar e implementar la arquitectura correcta para tu caso. Diagnóstico gratuito con recomendaciones técnicas personalizadas. Sin compromiso.

Solicitar Diagnóstico Gratis O escríbenos por WhatsApp

Solicita tu Diagnóstico Gratuito

Déjanos tus datos y te contactamos en menos de 24 horas.

Sin spam. Sin compromiso.