Qué configura tu negocio en WhatsApp Cloud API
En Integraciones → Canales de atención registras el Phone Number ID, el WABA ID, el token de acceso permanente y el secreto de aplicación de Meta correspondientes a tu negocio. El servidor cifra estos secretos con AES-256-GCM antes de guardarlos y nunca vuelve a exponerlos en texto plano al navegador.
Guardar las credenciales marca el canal como configurado en tu base de datos, pero no certifica por sí solo que Meta haya aprobado tu cuenta comercial, verificado tu número o activado el webhook hacia tu dominio público.
Cómo procesan los mensajes entrantes y salientes la API y el worker
En el entorno persistente la recepción y el despacho están desacoplados mediante la cola transaccional durable (outbox) para no perder eventos ni duplicar envíos.
| Etapa | Componente responsable | Comprobación de seguridad en servidor | Efecto si falla o falta configuración |
|---|---|---|---|
| Recepción de webhook | API NestJS (rawBody) | Valida la firma X-Hub-Signature-256 sobre los bytes originales, deduplica por wamid y ordena por received_at cuando coinciden en el mismo segundo. | Rechaza firmas inválidas sin tocar la base de datos e ignora reintentos con el mismo wamid. |
| Encolado de respuesta | Repositorio transaccional | Verifica permiso del operador o versión de automatización (modeVersion), ventana de 24 h y cuota disponible. | Guarda el mensaje como pending y registra el trabajo en outbox dentro de la misma transacción. |
| Despacho a Meta | Worker con lease durable | Revalida antes de enviar que el modo, la ventana, el consentimiento y el mensaje sigan vigentes. | Si el worker está detenido o falta credencial, permanece pending; si se corta la red tras enviar, pasa a uncertain sin reintentar a ciegas. |
Interpreta el estado antes de reintentar un envío
Pendiente (pending), enviado (sent), entregado, leído, fallido (failed) e incierto (uncertain) representan hechos distintos. Un estado uncertain indica que la petición salió hacia el proveedor pero no se recibió confirmación de respuesta: nunca reenvíes automáticamente ese mensaje sin comprobar primero si el cliente ya lo recibió.
Recuerda que la demostración local registra los mensajes en memoria para fines de recorrido visual y no se conecta con Meta.
Antes de continuar
- Comprueba que Phone Number ID, WABA ID y secreto de firma correspondan al mismo portafolio de Meta.
- Verifica con el diagnóstico operativo que tanto la API como el worker estén activos sobre la misma base PostgreSQL.
- Trata cualquier entrega en estado uncertain como un caso de revisión antes de volver a escribir.
La demo conserva datos en memoria. Las conexiones de proveedores requieren configuración, autorización y verificación en tu entorno persistente.