From 1c438c24c5ecfc691f8778cd20f93b9ec65da80f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Consultor=C3=ADa=20Alcaraz=20Salazar?= Date: Sun, 6 Sep 2026 09:06:01 +0000 Subject: [PATCH] Guia completa de uso del WACRM (revisado en vivo: webhook, envios, Sofia/Hermes, integracion SKEEN, limitaciones) --- docs/wacrm-guia-uso.md | 258 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 258 insertions(+) create mode 100644 docs/wacrm-guia-uso.md diff --git a/docs/wacrm-guia-uso.md b/docs/wacrm-guia-uso.md new file mode 100644 index 0000000..4546557 --- /dev/null +++ b/docs/wacrm-guia-uso.md @@ -0,0 +1,258 @@ +# WACRM — Guía de uso (SKEEN) + +> **Audiencia:** recepción, administración y personal no técnico de SKEEN. +> **Última revisión:** 2026-09-06 (basada en revisión del código y pruebas en vivo del sistema; ver sección 6 "Estado actual"). +> Documento de referencia técnica general: `docs/arquitectura.md`. + +--- + +## 1. ¿Qué es y para qué sirve? + +**WACRM** es el CRM de WhatsApp de la clínica. Permite que el personal de SKEEN: + +- **Reciba en una bandeja** todos los mensajes de WhatsApp que los pacientes mandan al número de la clínica. +- **Responda** esos mensajes desde la computadora, como equipo (varias personas pueden ver la misma bandeja). +- **Asigne cada conversación a un agente** (quién se hace cargo del paciente). +- **Administre leads** (pacientes potenciales que escriben por primera vez) y conviértelos en **pacientes** del sistema, quedando todo ligado a la clínica. +- Tenga un **asistente de inteligencia artificial ("Sofía")** que atiende automáticamente: responde dudas, y sobre todo **agenda citas reales** en el sistema (consulta la disponibilidad de Odoo y crea la cita). + +Hay **dos formas de usarlo** (sección 2): integrado dentro del sistema SKEEN (recomendado para el trabajo diario) o el WACRM "completo" en su propia pantalla (para administración: plantillas, difusiones, automatizaciones, configuración). + +--- + +## 2. Cómo acceder + +### 2.1 Desde el sistema SKEEN (recomendado para el día a día) + +1. Entre a **http://192.168.10.114** (el sistema SKEEN normal) e inicie sesión con su usuario y contraseña habituales. +2. En el menú lateral encontrará dos secciones: + - **Mensajes WACRM** (`/wacrm/messages`) — la bandeja de WhatsApp. + - **Leads WACRM** (`/wacrm/leads`) — el embudo de leads. + +> Si no ve esas opciones en su menú, pida al administrador que se las habilite desde *Configuración → menús por usuario*. + +### 2.2 WACRM directo (standalone) + +- **URL en la red de la clínica:** `http://192.168.10.114:3000` +- **Dominio público configurado:** `https://skeencrm.consultoria-as.com` (el dominio interno es `skeencrm.consultoria-as.com`; el túnel Cloudflare activo en la VM enruta hoy solo `skeen.consultoria-as.com` — si el dominio de WACRM no abre, use la IP :3000 o pida a TI revisarlo). +- **Login:** correo + contraseña (cuentas existentes: `admin@skeen.mx`, `recepcion@skeen.mx`, `ivan@horuxfin.com`; hay también una cuenta de prueba `test@skeen.mx`). Si olvida la contraseña, use "¿Olvidaste tu contraseña?" o pida a un administrador que la restablezca. +- Al crear una cuenta nueva desde "Sign up" se entra a una **cuenta propia**; para trabajar en el mismo equipo se entra por **enlace de invitación** que el administrador envía desde Configuración (se acepta en la pantalla `/join/`). + +### 2.3 Roles en WACRM directo + +Cada cuenta tiene roles: **owner** (dueño), **admin**, **agent** y **viewer**. Las configuraciones críticas (número de WhatsApp, plantillas, equipo) solo las maneja owner/admin. + +--- + +## 3. Flujo diario de trabajo + +El ciclo normal de un paciente que escribe por WhatsApp es: + +``` +Paciente escribe al WhatsApp de la clínica + │ + ▼ +Sofía (IA) lo saluda y atiende sola ◄────────────┐ + • agenda citas (disponibilidad real) │ mientras la conversación + • da precios/servicios │ NO esté asignada a un humano + • consulta pagos / monedero │ + │ (si el paciente pide un agente, │ + │ o recepción ASIGNA la conversación) │ + ▼ │ +Agente humano toma el hilo ───────────────────────┘ + │ + ▼ +Leads WACRM: se crea un lead "New Lead" por cada contacto con conversación + │ mover etapa / asignar responsable + ▼ +Lead ganado → "Convertir" → se crea (o liga) el PACIENTE en SKEEN +``` + +**Rutina recomendada cada mañana (y cada hora pico):** + +1. Entre a **Mensajes WACRM**. Presione **Sincronizar** (tarda hasta ~1 minuto la primera vez; trae todo lo nuevo). + - La pantalla también se refresca sola cada ~15 segundos. +2. Filtre por **"No leídas"** y **"Sin asignar"**: esos son los chats que necesitan atención. +3. Si Sofía ya resolvió el caso (ej. la cita ya quedó agendada), no hay que hacer nada. +4. Si hay que atender a mano: **Asignar** la conversación a una persona → **seleccione "Responder como…"** (su identidad de agente) → escriba y envíe. + - **Al responder, la conversación queda automáticamente asignada a usted y el bot deja de intervenir** en ese chat. +5. Si el contacto es nuevo, use el enlace **"No es paciente — Crear paciente"** para darlo de alta desde la misma pantalla (o hágalo después desde Leads). +6. En **Leads WACRM** revise los leads nuevos: clasifíquelos (etapas), asígnelos, y cuando el paciente agenda/compra, márquelos **ganado** (idealmente con "Convertir en paciente"). + +--- + +## 4. Pantalla por pantalla + +### 4.1 Mensajes WACRM (sistema SKEEN → `/wacrm/messages`) + +| Elemento | Qué hace | +|---|---| +| Buscador | Busca conversaciones por nombre o teléfono del contacto. | +| Botón **Sincronizar** | Trae a la pantalla los datos más recientes de WACRM (contactos, conversaciones, mensajes). Dura hasta ~1 minuto porque baja los ~9,700 contactos; espere el mensaje de confirmación. | +| **Responder como...** | Selector de identidad de agente. **Obligatorio** para poder escribir: los mensajes salen a nombre del agente elegido y asignan la conversación a él. | +| Filtros: Todas / Mías / Sin asignar / No leídas | "Mías" usa la identidad seleccionada. | +| Lista de conversaciones | Nombre, teléfono, último mensaje, hora y contador de no leídos. Chip azul = asignada a alguien. | +| Panel de chat | Historial completo. Cada burbuja indica quién escribió: **Cliente**, **Agente** o **Sofía (Bot)**. Botón **Asignar/Reasignar** arriba a la derecha (modal con el equipo; también "Desasignar conversación" en rojo — al desasignar, el bot vuelve a tomar el chat). | +| **Ficha del paciente** | Sobre el chat se muestra el paciente de SKEEN cuyo teléfono coincide (nombre, última visita, puntos de monedero). Si no existe, aparece **"No es paciente — Crear paciente"** para crearlo con un clic. | +| Caja de respuesta | Escriba y Enter/Enviar. El envío se hace por el mismo canal de WhatsApp de la clínica. | + +### 4.2 Leads WACRM (sistema SKEEN → `/wacrm/leads`) + +- **Vistas:** Kanban (tarjetas por etapa) y Lista. Botón **Sincronizar** igual que en Mensajes. +- **Filtros:** pipeline, estado (Abierto/Ganado/Perdido) y asignación (Todos / Sin asignar / Míos). Resumen con conteos y valores abiertos/ganados/perdidos. +- **Etapa** del lead: clic sobre la etapa (p. ej. "New Lead") para moverlo a otra etapa. Pipeline actual: **New Lead → Qualified → Proposal Sent → Negotiation → Won**. +- **Estado:** botones ✔ (ganado) y ✖ (perdido) en cada fila/tarjeta. +- **Asignar responsable** a cada lead (modal con los agentes). +- **Convertir en paciente:** botón que crea (o liga si ya existe) el **paciente en SKEEN** usando el teléfono del contacto, y marca el lead como ganado. Es idempotente: si ya estaba convertido, solo muestra el paciente. +- **Ir a la conversación:** enlace directo al chat del lead en Mensajes WACRM. +- Los leads **se crean automáticamente**: cada vez que se sincroniza, todo contacto con conversación de WhatsApp y sin lead abierto recibe un lead "New Lead". No es necesario crearlos a mano. + +### 4.3 WACRM directo (standalone) + +| Sección | Para qué sirve | +|---|---| +| **Dashboard** | KPIs generales de la operación de WhatsApp. | +| **Inbox** | La misma bandeja de conversaciones, versión nativa de WACRM (equivalente a "Mensajes WACRM" del sistema SKEEN). | +| **Contacts** | Directorio de contactos: teléfono, nombre, etiquetas, notas y campos personalizados. Aquí están los ~9,700 contactos históricos. | +| **Pipelines** | El embudo de leads (mismo pipeline que se ve en SKEEN), en tablero Kanban. | +| **Broadcasts** | Envíos masivos por **plantilla de WhatsApp**. **Hoy no es utilizable: no hay plantillas cargadas/aprobadas** (ver sección 6). | +| **Automations** | Reglas automáticas ("cuando entra un mensaje nuevo → hacer X"). Hoy tiene una sola regla activa: *"Nuevo mensaje → Webhook Hermes Bridge"*, que es la que conecta con Sofía — **no desactivarla**. | +| **Flows** | Flujos conversacionales con nodos (menús con botones para el cliente). Hay un flujo "Welcome menu" en **borrador** (no activo); el agendamiento real lo hace Sofía, no los flows. | +| **Agents** | Playground de IA (pruebas de respuestas). | +| **Notifications** | Notificaciones internas de la plataforma. | +| **Settings** | Perfil/contraseña, **WhatsApp** (número y tokens de Meta), **plantillas**, equipo e invitaciones, API keys, apariencia, seguridad. La configuración del número de WhatsApp solo la debe tocar un administrador. | + +--- + +## 5. Sofía, la asistente de IA (WhatsApp) + +**Qué es:** el agente automático que contesta el WhatsApp de la clínica. En la bandeja sus mensajes aparecen como **"Sofía (Bot)"**. + +**Qué puede hacer por sí sola:** + +- **Agendar citas reales** paso a paso: pregunta el servicio (catálogo real de SKEEN), el día, muestra los **horarios disponibles de la agenda real**, pide el nombre y **crea la cita en el sistema** y la confirma al paciente. El paciente puede interrumpir o escribir "cancelar" en cualquier momento. +- Informar de **servicios y precios** (consulta el catálogo de SKEEN). +- Consultar **pagos pendientes** y **monedero/puntos** del paciente (por teléfono). +- Orientar en general sobre la clínica (horarios, dirección) cuando la pregunta no encaja en lo anterior. + +**Reglas de conducta (cómo decide cuándo responder):** + +1. Responde **únicamente a mensajes que el paciente envía** (no a los que la clínica manda). Responde **24/7** — no tiene restricción de horario. +2. **Si la conversación está asignada a un agente humano, Sofía NO responde** en ese chat. Desasignar la conversación devuelve el control al bot. +3. Si el paciente escribe **"agente", "humano", "especialista", "doctor(a)" o "recepcionista"**, Sofía anuncia que la atenderá recepción y deja de responder automáticamente ese chat (el equipo debe verlo en la bandeja y hacerse cargo). +4. Si hay un agendamiento en curso, continúa donde se quedó aunque el paciente escriba varias cosas ("mañana", "a las 9 am", etc.). +5. Tiene memoria por número de teléfono (recuerda el hilo reciente de cada paciente). + +**Cómo tomar el control humano:** simplemente **asigne la conversación a un agente** (o respóndala; el envío la asigna solo). Para devolverla al bot, **desasígnela**. + +**Dónde ver sus respuestas:** en la misma bandeja (Mensajes WACRM / Inbox), con la etiqueta "Sofía (Bot)". + +--- + +## 6. Estado actual y limitaciones (revisado el 2026-09-06) + +**Lo que FUNCIONA hoy (verificado en vivo):** + +- ✅ Recepción de mensajes: el webhook de WhatsApp está configurado y firmado; los mensajes de clientes entran y aparecen en la bandeja. +- ✅ Envío de respuestas: el número de WhatsApp **+52 1 663 700 6400** está conectado, con token válido y calidad **GREEN** ante Meta; las respuestas del equipo y de Sofía salen de verdad por WhatsApp. +- ✅ Sofía responde y agenda citas (probado con flujos reales: el 10-jul-2026 completó un agendado completo, y el 3-sep-2026 contestó un saludo). +- ✅ Bandeja y leads integradas en el sistema SKEEN, con asignación y conversión a paciente. +- ✅ Sincronización SKEEN ↔ WACRM funcionando (ver abajo cuánto tarda). + +**Lo que está a medias o apagado — importante:** + +- ⚠️ **Recordatorios automáticos de citas: APAGADOS a propósito.** El módulo existe (recordatorio 24 h antes, follow-up post-tratamiento, re-engagement a 90 días) y hasta está programado en la configuración, pero está **desactivado deliberadamente** hasta que la clínica use un **número de WhatsApp propio de SKEEN** (el número actual está registrado a nombre *"Consultoria Alcaraz Salazar"*). No activarlo hasta que el cliente lo autorice. +- ⚠️ **Plantillas de WhatsApp: ninguna cargada (0).** Consecuencias: (a) los **Broadcasts** (difusiones masivas) no funcionan; (b) **no se puede escribir a un paciente fuera de la ventana de 24 horas** (regla de WhatsApp: solo con plantilla aprobada se puede iniciar conversación). Las plantillas requieren aprobación de Meta — pendiente del cliente. +- ⚠️ **La IA "nativa" de WACRM está desactivada** (no hay configuración IA en la cuenta). La IA que atiende es **Sofía (Hermes)**. Si alguien activa la IA nativa en Settings sin coordinación, podría haber doble respuesta al cliente — no hacerlo. +- ⚠️ **El botón "Sincronizar" tarda ~1 minuto** (baja los 9,747 contactos completos). Es normal; no repetirlo insistentemente. +- ⚠️ Si se **elimina** una conversación en WACRM, en el sistema SKEEN puede seguir apareciendo un tiempo (la sincronización agrega/actualiza pero **no borra** registros viejos). Filtre por los chats activos. +- ⚠️ Definir si los chats **entran en horario no laboral**: Sofía responde de noche y fines de semana (no tiene límite horario). Si la clínica prefiere que no responda fuera de horario, es un ajuste pendiente de definir. + +--- + +## 7. Solución de problemas + +| Síntoma | Causa probable / qué hacer | +|---|---| +| **No llegan mensajes nuevos de clientes** | 1) Presione **Sincronizar** y espere ~1 min. 2) Si tampoco aparecen en el WACRM directo (Inbox), el problema es del webhook de Meta → avise a TI (revisar token/número en Settings → WhatsApp). | +| **No me deja escribir** ("Selecciona tu identidad de agente") | Elija su nombre en el selector **"Responder como..."** de la barra superior. | +| **Envío falla / no sale el mensaje** | Verifique que el mensaje sea a un número válido. Si el paciente **no ha escrito en las últimas 24 h**, WhatsApp bloquea el mensaje libre → se necesita plantilla aprobada (hoy ninguna cargada). Avise a TI si el error persiste. | +| **El bot responde cuando no debe** | **Asigne la conversación a un agente** (botón Asignar). En cuanto esté asignada, Sofía se calla. Desasignar vuelve a activarla. | +| **El bot no responde cuando debería** | ¿La conversación quedó asignada a alguien? Desasígnela. ¿El paciente escribió "agente/humano/doctor"? Es handoff intencional — atiéndalo usted o desasigne si fue error. Si sigue sin responder, avise a TI (revisar servicios del bridge/gateway, sección 8). | +| **Veo conversaciones que ya no existen** | El listado del sistema SKEEN es un caché; la sincronización no borra. Use Sincronizar y concentre el trabajo en los chats activos. | +| **Sincronizar tarda mucho o parece travado** | Normal hasta ~1 minuto (9,747 contactos). Si falla, reintente; si falla dos veces, avise a TI. | +| **No me llegan recordatorios de citas a los pacientes** | **Esperado por ahora** — los recordatorios están apagados hasta tener el número de SKEEN y plantillas aprobadas (sección 6). | + +--- + +## 8. Anexo técnico (breve) + +### 8.1 Arquitectura + +``` +Paciente (WhatsApp) + │ Meta Cloud API (número +52 1 663 700 6400, calidad GREEN) + ▼ +Webhook → WACRM Next.js :3000 (valida firma Meta, guarda contacto/ + conversación/mensaje, corre flows + automations) + │ notifica message.received + ▼ +Hermes Bridge :8090 (webhook-bridge.js) + │ omite la conversación si está asignada a humano (consulta a Odoo) + ▼ +Hermes Gateway :8080 (LLM "Sofía" — proveedor Nan Builders, modelo qwen3.6) + │ intents: agendar / servicios / monedero / pagos / otro + │ agendado: disponibilidad y creación de CITA real vía API de Odoo + ▼ +Respuesta → WACRM API (/api/v1/messages) → Meta → paciente + +Sistema SKEEN (React :80 + Odoo :8069) + └─ proxy /skeen/frontend/v1/wacrm/* → caché local skeen.wacrm.* + (sync desde Supabase; envío vía bridge; asignación; leads; conversión) +``` + +- **BD del WACRM:** Supabase self-hosted (Docker, API en :8000; tablas: contacts, conversations, messages, deals, pipelines, message_templates, automations, flows, ai_configs, whatsapp_config…). Los mensajes **se guardan en Supabase**; Odoo guarda una **copia de trabajo** (modelos `skeen.wacrm.*`). +- **Odoo** es la fuente de verdad de: catálogo/servicios, disponibilidad de agenda, citas creadas por Sofía y pacientes (la conversión de lead crea `res.partner` con `is_patient=True, source='whatsapp'`). + +### 8.2 Componentes y servicios + +| Componente | Puerto | Servicio / proceso | Reinicio | +|---|---|---|---| +| WACRM (Next.js) | 3000 | `wacrm.service` (`npm start`, dir `/root/skeen-wacrm`) | `systemctl restart wacrm` | +| Hermes Gateway (IA) | 8080 | `hermes-gateway.service` (venv `/root/hermes-venv`) | `systemctl restart hermes-gateway` | +| Hermes Bridge | 8090 | **⚠️ ver nota** — el unit `hermes-bridge.service` está en bucle de reinicios; el proceso real sirve desde un `nohup node webhook-bridge.js` (dir `/root/skeen-roadmap-hermes/hermes`) | Matar el PID real y luego `systemctl restart hermes-bridge` (ver nota) | +| Odoo | 8069 | `odoo-skeen.service` | `systemctl restart odoo-skeen` | +| Nginx | 80 | `nginx` | `systemctl reload nginx` | +| Supabase | 8000 | Docker (contenedores `supabase-*`) | `docker compose restart` en su dir | +| Túnel público | — | `cloudflared-skeen.service` (`/root/.cloudflared/config.yml`) | `systemctl restart cloudflared-skeen` | + +**⚠️ Nota sobre el bridge (verificada el 2026-09-06):** desde el 14-ago-2026 existe un proceso `node webhook-bridge.js` iniciado con `nohup` (log en `/tmp/hermes-bridge.log`) que **ocupa el puerto 8090**. El servicio systemd `hermes-bridge` arranca cada 5 s, encuentra el puerto ocupado (EADDRINUSE) y sale con código 0 — acumulando cientos de miles de "reinicios" en el log. **Consecuencia práctica:** el bridge SÍ está funcionando (es el proceso nohup), pero `systemctl stop hermes-bridge` **no** lo detiene. Para operar de forma limpia: `kill ` y dejar que systemd lo levante (en puerto libre arranca y queda estable), o desactivar el nohup viejo. Es un pendiente de mantenimiento. + +**Health-check rápido:** +- Bridge: `curl http://localhost:8090/health` → `{"status":"ok",...}` +- WACRM: `curl -o /dev/null -w '%{http_code}' http://localhost:3000/login` → `200` +- Gateway (IA): `systemctl status hermes-gateway` + +### 8.3 Configuración y datos (rutas) + +| Componente | Ubicación | +|---|---| +| Código WACRM | `/root/skeen-wacrm` (Next.js + Supabase; credenciales Meta en `wacrm.service` / `.env.local`) | +| Bridge | `/root/skeen-roadmap-hermes/hermes/webhook-bridge.js` (memoria de Sofía por teléfono en `.../hermes/memory/.json`) | +| Config Hermes | `/root/.hermes/config.yaml` (gateway :8080, plataforma webhook :8644, skills SKEEN) | +| Proxy/ caché Odoo | `/root/skeen-odoo/addons/skeen_whatsapp/controllers/wacrm_proxy.py` y `models/wacrm_sync.py` | +| Páginas del sistema SKEEN | `/root/skeen-frontend/src/pages/WacrmMessages.tsx`, `WacrmLeads.tsx` | +| Webhook público del bridge | `https://skeen.consultoria-as.com/webhook/wacrm` (nginx → :8090) | + +### 8.4 Endpoints del proxy (para TI) + +`POST /skeen/frontend/v1/wacrm/sync` · `GET /wacrm/conversations` · `GET|POST /wacrm/messages` · `GET /wacrm/members` · `POST /wacrm/conversations//assign` · `GET /wacrm/conversations//assigned` · `GET /wacrm/pipelines` · `GET /wacrm/leads` · `PUT /wacrm/leads//status` · `POST /wacrm/leads//convert` — todos bajo `/skeen/frontend/v1/`, autenticados con token del frontend SKEEN. + +### 8.5 Interruptores conocidos (pendientes del cliente) + +| Interruptor | Dónde | Estado | +|---|---|---| +| Recordatorios de citas | bridge `REMINDERS_ENABLED=true` + heartbeat | **OFF a propósito** (hasta número SKEEN + plantillas + opt-in). Cron del gateway también sin ejecuciones. | +| Re-engagement 90 días | bridge `REENGAGE_ENABLED=true` | OFF | +| Plantillas de WhatsApp | Meta Business + Settings → Templates del WACRM | 0 cargadas → Broadcasts inoperantes | +| IA nativa WACRM (`ai_configs`) | Settings → AI | Desactivada; usar Sofía (Hermes) |