Guía para crear un CRM

Arquitectura de referencia para construir un inbox, agente o automatización sobre Nahui Connect sin depender del almacenamiento de Nahui.

Arquitectura mínima

Arquitectura

WhatsApp del contacto
        ↓
Meta Cloud API
        ↓
Nahui Connect
        ↓ POST firmado
Webhook de tu backend
        ↓
Validación + deduplicación
        ↓
Base de datos / reglas / IA / atención humana
        ↓
Respuesta inmediata o POST /reply
        ↓
Nahui Connect → Meta → contacto

Responsabilidades del backend

Recibir el cuerpo crudo y verificar X-Nahui-Signature-256.
Deduplicar por deliveryId.
Convertir el evento a tu modelo interno y guardar historial si tu producto lo necesita.
Ejecutar reglas o llamar a la IA.
Responder inmediatamente o en segundo plano.
Proteger API key y secreto.

Tablas mínimas sugeridas

Tabla	Campos sugeridos
`connections`	id, nahui_connection_id, name, status, referencia segura al secreto
`contacts`	id, connection_id, nahui_contact_id, display_name, created_at, updated_at
`conversations`	id, connection_id, nahui_conversation_id, contact_id, status, assigned_user_id, last_message_at
`messages`	id, conversation_id, nahui_message_id, direction, type, body, payload_json, created_at
`webhook_deliveries`	delivery_id UNIQUE, event_id, received_at, processed_at, status
`outbound_operations`	idempotency_key UNIQUE, conversation_id, kind, status, attempts, last_error

No uses displayName como identificador. Usa contact.id junto con connectionId. El historial que guardes pertenece al CRM, no a Nahui.

Agente de IA

Recibe y verifica el evento.
Busca los últimos mensajes en la base del CRM.
Aplica reglas para decidir si responde la IA o un humano.
Llama al proveedor de IA.
Valida y limita la salida a 4,000 caracteres.
Responde de manera síncrona si queda tiempo suficiente.
Si no, usa una cola y /reply.

No envíes el secreto, la API key ni el evento completo como instrucciones no confiables al modelo.

Atención humana

El frontend habla con tu backend, nunca directamente con Nahui.
El backend valida permisos del agente humano.
El backend llama a /reply con la API key protegida.
Registra quién envió cada respuesta.
Usa una nueva Idempotency-Key para cada mensaje humano.

Manejo de medios

El evento incluye media.id, mimeType, caption y filename cuando Meta los proporciona. La versión actual no documenta un endpoint de Nahui para descargar el binario: no asumas que media.id es una URL y no fabriques una.

Estados recomendados

Entrega entrante

received → verified → processing → completed / failed

Salida

pending → sending → sent / retryable_error / permanent_error

Prueba de aceptación

Rechaza un webhook con firma incorrecta y acepta uno firmado.
Procesa dos veces el mismo deliveryId sin duplicar mensajes.
Devuelve una respuesta inmediata válida y envía una respuesta asíncrona usando conversationId.
Un reintento con la misma Idempotency-Key devuelve duplicate: true.
Nunca envía teléfonos a endpoints de Nahui.
Maneja 429 y 502.
Los secretos nunca aparecen en frontend, logs o repositorio.
Un tipo de mensaje desconocido no derriba el webhook.