Nahui Connect
Nahui Connect / Documentación

Inicio rápido

Configura WhatsApp, verifica el webhook y responde sin exponer credenciales ni destinatarios.

Pasos
1. Crear conexión2. Variables3. Recibir4. Responder5. Idempotencia

1. Crear y configurar la conexión

  1. Crea un proyecto en Nahui Connect.
  2. Crea una conexión de WhatsApp.
  3. Registra una URL HTTPS pública, por ejemplo https://tu-dominio.com/webhooks/nahui.
  4. Genera credenciales y guarda la API key y el secreto; Nahui solo los muestra completos al generarlos.
  5. Conecta WhatsApp mediante el flujo oficial de Meta.
Configura primero el webhook y las credenciales. Si conectas el canal sin webhook, los mensajes entrantes pueden contabilizarse sin llegar a tu sistema.

2. Variables de entorno

dotenv
NAHUI_CONNECTION_ID=ncc_...
NAHUI_API_KEY=nhc_...
NAHUI_WEBHOOK_SECRET=nhs_...
NAHUI_API_BASE=https://api.nahui.studio

Nunca uses estas variables en JavaScript enviado al navegador.

3. Recibir el evento

Tu endpoint debe aceptar POST application/json, conservar el cuerpo crudo y verificar la firma. El orden operativo es:

Orden obligatorio
leer bytes → validar firma → revisar deliveryId → parsear JSON → procesar

4. Elegir estrategia de respuesta

Respuesta síncrona

Úsala cuando la respuesta esté lista con margen antes de 15 segundos.

JSON
{
  "reply": {
    "text": "Respuesta del CRM o agente"
  }
}

Esta respuesta forma parte del mismo flujo entrante y no consume un segundo mensaje de Connect.

Procesamiento asíncrono

Para modelos lentos, varias consultas externas, aprobación humana, colas o workflows, responde primero:

HTTP 200 · application/json
{}

Después llama al endpoint de respuesta:

POSThttps://api.nahui.studio/v1/connect/relay/{connectionId}/reply

No mantengas abierto el webhook hasta el límite exacto. La guía recomienda un presupuesto interno de 10–12 segundos.

5. Implementar idempotencia

Entrante

Inserta deliveryId con restricción única. Si ya existe, responde 200 sin repetir efectos.

Saliente

Genera una clave por mensaje lógico y guárdala antes de llamar a Nahui. Si hay timeout, reintenta con la misma clave.

Ejemplo de Idempotency-Key
crm:reply:{uuid_o_ulid}