wa-audit

Una auditoría comercial de tu número de WhatsApp. Apúntalo a una instancia de WAHA y exporta el historial completo de chats, construye un corpus de conversaciones limpio, ejecuta un análisis con LLM que se verifica contra el corpus antes de que llegue a ti y entrega un informe XLSX de varias hojas: tiempos de respuesta, preguntas frecuentes reales, arquetipos de clientes, objeciones, lo que un bot podría resolver de verdad — con una hoja de metodología que registra lo que la verificación refutó.

Todo se ejecuta en tu máquina. El único tráfico saliente en todo el pipeline es la llamada de análisis de la fase 4 al proveedor de LLM que tú configures — y eso también desaparece con llm.provider: "mock" o un endpoint compatible con OpenAI autoalojado, para una ejecución totalmente offline.

Leé esto en castellano: README.es.md.

⚠️ Leé esto primero

Este proyecto no está afiliado, asociado, autorizado, respaldado ni conectado oficialmente de ninguna manera con WhatsApp, Meta Platforms Inc., ni con ninguna de sus subsidiarias. "WhatsApp" y "Meta", y los nombres, marcas e imágenes relacionados, son marcas comerciales de sus respectivos propietarios. El sitio web oficial de WhatsApp es https://whatsapp.com.

Tampoco está afiliado al proyecto WAHA. Esta herramienta solo consume la API HTTP de una instancia de WAHA que tú operas; no redistribuye, incluye ni modifica WAHA (que es Apache-2.0, obtenible desde su repositorio oficial).

WAHA utiliza métodos no oficiales para acceder a WhatsApp. WhatsApp no permite bots ni clientes no oficiales en su plataforma, y no hay garantía de que tu cuenta no sea bloqueada. Los mantenedores de este proyecto no aprueban ningún uso que viole los Términos de Servicio de WhatsApp y desaconsejan explícitamente el envío masivo de mensajes, el spam, el stalkerware o la vigilancia de personas. Para integraciones críticas para el negocio, considerá la API oficial de WhatsApp Business. El caso de uso previsto es que una empresa analice su propio historial de conversaciones.

Datos personales: el historial de chats son datos personales de terceros. Sos el único responsable de tener una base legal válida para procesarlos y de cumplir con la ley que te aplica (GDPR, LGPD, Ley 25.326, …). El procesamiento ocurre en tu propia infraestructura y este proyecto no transmite nada a sus autores. El único flujo saliente es la fase de análisis, que envía un resumen del corpus al proveedor de LLM que configures — ninguno con un proveedor local o mock. Elegí tu proveedor en consecuencia.

Este software se proporciona "TAL CUAL", sin garantía de ningún tipo.

Related MCP server: Wasapi MCP Server

Por qué el verificador es el punto central

Este pipeline fue construido para un negocio real: 11.782 mensajes, 610 conversaciones, 8 meses de historial. El análisis con LLM produjo 60 hallazgos en 7 dimensiones. Luego, cada dimensión pasó por un verificador independiente que reubicó cada cita y recontó cada afirmación contra el corpus.

El verificador refutó 34 de los 60 hallazgos.

Hallazgos plausibles, bien redactados, con números confiados — y más de la mitad no sobrevivieron al contacto con los datos. Un análisis con LLM de tu negocio sin una pasada de verificación no es análisis; es ficción con buen formato. Por eso en este proyecto:

• cada hallazgo debe citar evidencia textual (thread_id + cita), y una verificación de código determinista refuta cualquier hallazgo cuya cita no exista en el corpus — ningún modelo tiene voto en eso;

• una segunda pasada de LLM independiente recuenta cada afirmación de frecuencia y refuta lo que no se sostiene tal como se afirma;

• el esquema hace que el veredicto sea obligatorio: un análisis sin una pasada de verificación registrada es inválido por construcción;

• la hoja de metodología del informe imprime los hallazgos refutados, para que nadie vuelva a citar los números incorrectos después.

Dos lentes de análisis: comercial + conductual FATE

El análisis incluye dos conjuntos de dimensiones, ambos sujetos a la misma verificación obligatoria:

• Comercial (7 dimensiones): preguntas frecuentes reales, tiempos de respuesta y operaciones, arquetipos de clientes, productos y temas, objeciones y fricciones, oportunidades de bot, tono y estilo.

• Conductual FATE (5 dimensiones, npm run analyze -- --dimensions fate): cómo el negocio capta la atención (Focus), proyecta certeza y cumple su palabra (Authority), hace que los clientes se sientan comprendidos (Tribe), llega a la capa emocional en lugar de soltar especificaciones (Emotion), y lee las señales de estado del cliente — solo clústeres, explicaciones benignas primero, estados, nunca veredictos sobre individuos. Inspirado en el modelo FATE de Chase Hughes en The Behavior Ops Manual (articulación original; no afiliado ni respaldado por el autor). Entrevistá primero a tu operador y cargá business-context.json — ver analysis/PLAYBOOK.md.

Probálo en dos minutos (sin necesidad de WhatsApp)

git clone https://github.com/Leandrozz/wa-audit && cd wa-audit
npm install
npm run demo

La demo genera un corpus sintético, inicia un servidor WAHA mock, ejecuta todo el pipeline contra él (sonda → exportación → corpus → análisis verificado → informe) con un LLM mock, y deja el informe en out/demo/ en los tres formatos — XLSX (la hoja de cálculo del cliente), HTML (archivo único compartible) y DOCX (Word). Sin claves, sin red, sin datos reales.

Ejecutalo contra tu WhatsApp real

Necesitás una instancia de WAHA en funcionamiento con tu número de negocio conectado — ver docs/waha-setup.md para las trampas que nos costaron días (elección del motor, fullSync, ranuras de dispositivo, @lid).

cp waha.env.example waha.env        # fill in WAHA_BASE_URL + WAHA_API_KEY
# 0. read-only probe: right engine? how deep does the history go?
node --env-file=waha.env src/probe.mjs
# 2. dump the raw history (resumable)
node --env-file=waha.env src/export.mjs <session-name>
# 3. clean corpus: threads.json + messages.csv + summary.json
node --env-file=waha.env src/threads.mjs --session <session-name>
# 4. LLM analysis with mandatory verification (needs ANTHROPIC_API_KEY,
#    or any OpenAI-compatible endpoint — see Configuration)
node --env-file=waha.env src/analyze.mjs
# 5. the report, in any or all formats
node src/report-xlsx.mjs && node src/report-html.mjs && node src/report-docx.mjs

¿Preferís ejecutar el análisis con tu propio agente (Claude Code, Cursor, lo que sea) en lugar del motor integrado? Ese es un camino de primera clase: analysis/PLAYBOOK.md.

El camino de la API oficial (Kapso)

Si el número funciona en la Plataforma oficial de WhatsApp Business a través de Kapso, omití WAHA por completo — sin cliente no oficial, sin descargo de responsabilidad de ToS para esta fuente, sin @lid:

cp kapso.env.example kapso.env      # KAPSO_API_KEY + KAPSO_PHONE_NUMBER_ID
npm run export:kapso
node src/threads.mjs --session kapso --no-net

Mismo corpus, mismo verificador, mismos informes. Una compensación honesta: la plataforma oficial no tiene retroalimentación retroactiva, así que el historial cubre lo que fluyó a través de Kapso desde que el número se conectó allí. Detalles y un servidor mock para probarlo sin cuenta: docs/kapso-setup.md.

O dejá que Claude maneje todo (MCP)

npm run mcp inicia un servidor MCP que convierte a Claude Desktop / Claude Code / ChatGPT / Cursor en el motor de auditoría: el agente te entrevista, guía la configuración de WAHA, muestra el QR de emparejamiento directamente en el chat, exporta el historial y ejecuta el análisis él mismo. El servidor lo mantiene honesto estructuralmente — submit_dimension rechaza cualquier dimensión sin un veredicto de verificación registrado, cada cita de evidencia se vuelve a verificar del lado del servidor contra el corpus, y el contenido del chat se sirve como datos no confiables. Nunca envía un mensaje de WhatsApp. Configuración: docs/mcp-setup.md.

El pipeline

 probe ──► export ──► threads ──► analyze ──► report-xlsx
 (0)       (2)        (3)         (4)         (5)
 read-only raw dump   clean       LLM + two-  11-sheet XLSX
 sanity    JSONL,     corpus,     layer       with styles,
 check     resumable  @lid        verifier    frozen panes &
                      resolution              a methodology
                      + metrics               sheet

Cada fase lee y escribe archivos locales simples (por defecto data/wa-history/), así que podés volver a ejecutar cualquier fase sin repetir las anteriores — el volcado nunca se vuelve a raspar debido a un error de análisis.

Configuración

Copiá wa-audit.config.json y editá, o usá anulaciones de entorno (el entorno gana). Lo esencial:

Los secretos son solo de entorno: WAHA_BASE_URL, WAHA_API_KEY (+ ANTHROPIC_API_KEY o LLM_API_KEY para la fase 4). WAHA_BASE_URL no tiene valor por defecto a propósito — apuntar a la instancia equivocada es el error costoso.

La prosa del informe es actualmente en español (preset es-AR); el contrato de datos subyacente está en inglés. La i18n de la prosa está en la hoja de ruta.

Contrato de datos

threads.json, summary.json y analysis.json tienen versión (schema_version: 1) y están documentados en docs/data-contract.md. El contrato de análisis está formalizado en analysis/analysis.schema.json (npm run check:analysis): cualquier motor que emita analysis.json válido — LLM, reglas, SQL, un humano — se conecta al informe sin cambios.

Limitaciones honestas

• El endpoint de historial masivo de WAHA solo existe en los motores NOWEB/GOWS; WEBJS requeriría exportación chat por chat (no soportado aquí — la sonda te lo dice).

• La profundidad del historial más allá de ~3 meses requiere crear la sesión con noweb.store.fullSync antes de volcar (docs/waha-setup.md).

• Las medianas de tiempo de respuesta se anclan en el primer mensaje de cada ráfaga entrante, y los mensajes salientes no distinguen humanos de bots — ambos se indican en la hoja de metodología del informe.

• Los medios no tienen texto analizable (downloadMedia=false): las fotos y notas de voz aparecen tipadas pero vacías.

• xlsx@0.18.5 (fijado: el post-procesamiento de estilos depende de él) tiene un aviso upstream conocido (prototype pollution / ReDoS en hojas de cálculo no confiables). Este proyecto solo escribe XLSX y lee su propia salida, así que el vector no aplica — pero npm audit lo marcará y preferimos decírtelo antes que ocultarlo.

• El estilo de XLSX funciona post-procesando el archivo como un ZIP — magia negra deliberada y documentada: docs/xlsx-postprocess.md.

Desarrollo

npm test                 # unit + two end-to-end lanes against goldens
node fixtures/generate.mjs   # regenerate the deterministic synthetic fixture
node test/record-golden.mjs  # re-record goldens (review the diff like a spec)

Todo en fixtures/ es sintético e inventado. No existe ninguna conversación, número de teléfono o nombre real de ningún negocio real en este repositorio.

Licencia

MIT.