Cómo Integrar la API de WhatsApp Business Cloud en Sistemas Web

La API oficial de WhatsApp Business permite que los sistemas envíen y reciban mensajes a través de la plataforma de Meta. No debe confundirse con la automatización de WhatsApp Web. Una integración confiable requiere una cuenta empresarial, un número configurado, permisos, webhooks verificados, plantillas aprobadas y tratamiento de consentimiento.

Respuesta directa

Crea o utiliza una cuenta de Meta for Developers, añade el producto WhatsApp, asocia el portafolio empresarial y el número, genera credenciales apropiadas en el servidor, envía un mensaje de prueba a través de la Graph API, configura un endpoint HTTPS para el webhook, valida el desafío, verifica la firma de los eventos y modela estados de envío, respuesta y error.

1. Prepara cuentas y activos

Necesitarás acceso administrativo a los activos empresariales, una aplicación en Meta y un número elegible. Para producción, revisa la verificación empresarial, el nombre de exhibición y el método de pago según lo requerido en el panel. Las pantallas y requisitos pueden cambiar; sigue el panel y la documentación oficial actual.

No utilices un número personal importante en pruebas sin entender la migración. Comienza con los recursos de prueba ofrecidos por la plataforma.

2. Protege el token

El token es una credencial de servidor. Nunca lo coloques en JavaScript enviado al navegador, aplicación móvil, impresión o repositorio. Almacénalo en una variable de entorno o en un cofre de secretos y concede solo los permisos necesarios.

Ejemplo de variables:

WHATSAPP_PHONE_NUMBER_ID=...
WHATSAPP_ACCESS_TOKEN=...
WHATSAPP_VERIFY_TOKEN=secreto-definido-por-usted
WHATSAPP_APP_SECRET=...

El verify token es elegido por usted para confirmar la configuración del webhook; no sustituye la verificación criptográfica de la firma recibida.

3. Envía un mensaje de prueba

Utiliza la versión actual de la Graph API indicada en el panel:

curl -X POST "https://graph.facebook.com/VERSAO/PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "55DDDNUMERO",
    "type": "template",
    "template": {"name": "hello_world", "language": {"code": "en_US"}}
  }'

No copies versión, ID o token de tutoriales antiguos. Registra el ID del mensaje devuelto y sigue sus estados posteriores a través del webhook.

4. Configura el webhook

El endpoint debe ser público y HTTPS. En la verificación inicial, Meta envía parámetros de desafío. Compara el token y devuelve el desafío cuando sea válido. Luego, los eventos llegan por POST.

Flujo recomendado:

recibir -> validar firma -> registrar ID -> responder 200 rápido
       -> encolar -> procesar -> actualizar conversación/estado

Valida X-Hub-Signature-256 utilizando HMAC SHA-256 con el app secret y el cuerpo bruto. Realiza comparaciones resistentes a timing. Rechaza firmas inválidas. El framework no debe modificar el cuerpo antes de la verificación.

5. Garantiza idempotencia

Los webhooks pueden repetirse. Almacena el identificador único del evento o mensaje y no proceses nuevamente el mismo efecto. Responde rápidamente y mueve reglas que tomen tiempo a la cola. Mantén un dead-letter y reintentos con límite.

6. Entiende ventana y plantillas

Los mensajes iniciados por la empresa normalmente utilizan plantillas aprobadas. Dentro de la ventana de atención abierta por la interacción del usuario, otros mensajes pueden ser permitidos según las reglas actuales. Las categorías, precios, límites y políticas cambian; consulta la documentación oficial antes de diseñar costos y operaciones.

Una plantilla debe ser clara y corresponder al uso aprobado. No transformes un mensaje transaccional en marketing disfrazado. Registra idioma, versión y variables para que los cambios sean auditables.

7. Modela estados

No marques un mensaje como entregado solo porque el POST devolvió éxito. Modela al menos:

Guarda el payload mínimo necesario y define retención. Relaciona cada mensaje con la conversación y el tenant correcto.

8. Trata consentimiento y atención

Recoge opt-in claro para la finalidad, ofrece salida y respeta preferencias. No importes listas sin base operativa. Orienta a los atendentes sobre transferencia, horario, historial y datos sensibles. La LGPD exige finalidad, transparencia y seguridad proporcionales; consulta orientación jurídica para tu caso.

9. Monitorea errores y calidad

Registra request ID, código normalizado, plantilla, destino enmascarado y latencia, nunca el token completo. Crea alertas para aumento de fallas, webhook sin eventos, cola acumulada y credencial cerca de expirar. Un panel debe separar aceptación, entrega y lectura.

El artículo integración vía API explica el diseño general, y automatización de integraciones muestra controles contra errores manuales.

Checklist de producción

• activos pertenecen a la cuenta de la empresa;
• token fuera del cliente y del repositorio;
• webhook HTTPS y firma validada;
• eventos idempotentes y procesados en cola;
• plantillas e idiomas versionados;
• opt-in y salida registrados;
• logs sin datos y secretos excesivos;
• alertas y panel de estado activos;
• política y precio revisados en la documentación actual;
• procedimiento de rotación e incidente documentado.

Preguntas frecuentes

¿Puedo usar una biblioteca que controla WhatsApp Web?

Esto no equivale a la API oficial y puede crear riesgos de estabilidad y política. Para operación empresarial, utiliza la plataforma oficial.

¿El retorno 200 significa que el mensaje fue entregado?

No. Informa la aceptación de la solicitud; la entrega se confirma por eventos de estado.

Fuentes primarias

• Meta: documentación de la WhatsApp Cloud API
• Meta: webhooks de la plataforma
• Meta: visión general de plantillas