WhatsApp Triage

Asistente personal de triage para WhatsApp Web.
Revisa chats no leídos o recientes, los prioriza, genera contexto accionable y deja un reporte local auditable.
Diseñado para operar en modo solo lectura y pensado, por ahora, para flujos con Codex.

---

WhatsApp Web + scoring de prioridad + inspección mínima + reporte auditable

Qué es esto

WhatsApp Triage convierte WhatsApp Web en una bandeja de entrada priorizada y auditable. En lugar de abrir chats uno por uno y decidir manualmente qué atender primero, el sistema:

• evalúa la barra lateral de WhatsApp Web
• detecta chats no leídos o recientes
• calcula prioridad, categoría y confianza
• inspecciona solo los casos ambiguos con una lectura mínima controlada
• genera resumen, razón de prioridad, acción sugerida y borrador opcional
• guarda evidencia local en Markdown y JSON

Importante: este proyecto no automatiza respuestas ni ejecuta acciones de escritura. Está diseñado como asistente de lectura y clasificación.

Principios del MVP

• Solo lectura: no envía mensajes, no archiva, no borra, no fija ni silencia chats.
• Inspección mínima: primero analiza sidebar y solo abre un chat cuando hace falta aumentar la confianza.
• Auditoría local: cada corrida deja reporte diario y snapshot JSON.
• Seguridad por defecto: no abre links, media, adjuntos ni sale de https://web.whatsapp.com.

Features

Feature	Descripción
Sidebar-first triage	Prioriza desde la barra lateral antes de abrir conversaciones
Scoring estructurado	Calcula score, category y confidence por chat
Inspección controlada	Abre solo chats ambiguos y relee pocos mensajes visibles
Resumen ejecutivo	Genera contexto breve para decidir qué atender primero
Acción sugerida	Propone siguiente paso para cada chat relevante
Borrador opcional	Puede preparar una respuesta sugerida si la confianza lo permite
Reporte auditable	Guarda reporte diario en Markdown y snapshot por corrida en JSON
Integración con Codex	Listo para ejecutarse como skill o automation conversacional

Qué hace

• abre WhatsApp Web con un perfil persistente local
• detecta chats no leídos o recientes
• clasifica en categorías de prioridad
• aplica reglas por contacto, keywords, recencia, grupos y mute
• genera resumen y siguiente acción sugerida
• guarda estado y salidas para trazabilidad

Qué no hace

• no envía mensajes
• no archiva ni borra chats
• no abre links, imágenes, audios ni adjuntos
• no usa APIs oficiales o no oficiales de WhatsApp
• no sale del dominio de WhatsApp Web

Inicio rápido

npm install
npx playwright install chromium
npm run login

Después del primer login manual, ejecuta:

npm run triage

Requisitos

• Node.js 20+
• npm
• Chromium instalado vía Playwright
• login manual inicial en WhatsApp Web

Configuración

Archivos principales:

• config/app.config.json
• config/triage-rules.json
• config/contacts-priority.example.json
• config/contacts-priority.json

Comportamiento de carga:

• si existe config/contacts-priority.json, se usa el archivo local
• si no existe, se usa config/contacts-priority.example.json como fallback
• el archivo local está ignorado por git para no subir datos sensibles

Formato recomendado para prioridades por contacto:

{
  "familia": ["Mama", "Papá", "Hijo", "Hija"],
  "trabajo": ["Jefe", "Boss", "Daily", "Equipo Producto"],
  "cliente": ["Cliente", "ACME"],
  "reclutador": ["Recruiter"],
  "amigo": [],
  "overrides": {
    "Grupo Dirección": { "tier": "trabajo", "scoreOverride": 30 }
  }
}

Variables opcionales:

• OPENAI_API_KEY: habilita resúmenes y borradores con LLM
• OPENAI_MODEL: override del modelo; por defecto usa gpt-4.1-mini

Uso

Login manual:

npm run login

Triage:

npm run triage

Validación local:

npm run typecheck
npm run test

Uso con Codex

La integración actual está pensada para invocarse como skill o intención conversacional dentro del workspace.

Puedes activarlo con cualquiera de estas formas:

• revisa mis mensajes de WhatsApp
• $whatsapp-triage
• /whatsapp login
• /whatsapp triage

Captura de ejemplo dentro de Codex:

Mapeo actual:

• /whatsapp login → npm run login
• /whatsapp triage → npm run triage

Si quieres que Codex lo descubra fuera de este repo, puedes enlazar la skill en ~/.codex/skills/whatsapp-triage.

Cómo funciona

WhatsApp Web
    │
    ▼
Escaneo de sidebar
    │
    ▼
Score + categoría + confianza
    │
    ├── confianza alta → resumen directo
    │
    └── confianza media/baja y score relevante
           ▼
     inspección mínima del chat
           ▼
     resumen + acción sugerida + snapshot

Política de inspección

Modo por defecto: open_when_needed

Flujo:

1. inspecciona primero la barra lateral
2. calcula score y confidence inicial
3. abre solo chats con score suficiente y confianza no alta
4. relee como máximo los mensajes visibles permitidos por configuración
5. registra openedForInspection e inspectionReason en el snapshot

Salidas

• reporte diario: reports/YYYY-MM-DD.md
• snapshot por corrida: state/runs/YYYYMMDDTHHMMSS.json
• registro de procesados: state/processed_chats.json
• último escaneo: state/last_scan.json
• evidencia de fallos: state/html y state/screenshots

Seguridad

• navega solo a https://web.whatsapp.com
• trata el texto de la UI como dato no confiable
• no ejecuta acciones destructivas
• no abre links ni media
• si falla un selector, captura evidencia y aborta

Estructura del proyecto

whatsapp-triage/
├── config/              # Reglas, app config y prioridades locales
├── reports/             # Reportes diarios en Markdown
├── skills/              # Skill para integración con Codex
├── src/                 # Núcleo del triage, clasificación e inspección
├── state/               # Estado persistente, snapshots y perfil local
└── tests/               # Cobertura unitaria del comportamiento principal

Stack

• Node.js para la ejecución CLI
• TypeScript para tipado y mantenibilidad
• Playwright para automatización segura de WhatsApp Web
• OpenAI como proveedor opcional de resumen y borradores
• Zod para validación de configuración y estructuras
• Vitest para pruebas

Casos de uso

• revisar rápidamente qué chats requieren atención inmediata
• separar ruido de mensajes importantes sin abrir toda la bandeja
• preparar una rutina diaria de triage personal
• dejar trazabilidad local de por qué un chat fue priorizado
• conectar el flujo con Codex para una revisión recurrente

Limitaciones conocidas

• depende de la estabilidad de los selectores de WhatsApp Web
• el primer login y algunas resincronizaciones son manuales
• abrir un chat puede alterar su estado visual según el comportamiento de la UI
• no sustituye revisión humana; prioriza y resume, pero no decide por ti

Licencia

MIT

Conectemos