wa-audit

Ein kommerzielles Audit deiner WhatsApp-Geschäftsnummer. Richte es auf eine WAHA-Instanz und es exportiert den vollständigen Chatverlauf, erstellt ein sauberes Gesprächskorpus, führt eine LLM-Analyse durch, die vor der Auslieferung gegen das Korpus verifiziert wird, und liefert einen mehrblättrigen XLSX-Bericht: Antwortzeiten, echte FAQs, Kundentypen, Einwände, was ein Bot tatsächlich lösen könnte – mit einem Methodikblatt, das festhält, was die Verifikation widerlegt hat.

Alles läuft auf deinem Rechner. Der einzige ausgehende Datenverkehr in der gesamten Pipeline ist der Analyseaufruf in Phase 4 an den LLM-Anbieter, den du konfigurierst – und selbst der entfällt mit llm.provider: "mock" oder einem selbst gehosteten OpenAI-kompatiblen Endpunkt für einen vollständig offline laufenden Betrieb.

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

⚠️ Bitte zuerst lesen

Dieses Projekt ist nicht verbunden mit, assoziiert mit, autorisiert von, unterstützt von oder in irgendeiner Weise offiziell verbunden mit WhatsApp, Meta Platforms Inc. oder deren Tochtergesellschaften. „WhatsApp“ und „Meta“ sowie zugehörige Namen, Marken und Bilder sind Marken ihrer jeweiligen Inhaber. Die offizielle WhatsApp-Website ist https://whatsapp.com.

Es ist auch nicht mit dem WAHA-Projekt verbunden. Dieses Tool nutzt lediglich die HTTP-API einer WAHA-Instanz, die du betreibst; es verteilt, bündelt oder modifiziert WAHA nicht (das unter Apache-2.0 steht und aus dem offiziellen Repository bezogen werden kann).

WAHA verwendet inoffizielle Methoden, um auf WhatsApp zuzugreifen. WhatsApp erlaubt keine Bots oder inoffiziellen Clients auf seiner Plattform, und es gibt keine Garantie, dass dein Konto nicht gesperrt wird. Die Betreuer dieses Projekts billigen keine Nutzung, die gegen die Nutzungsbedingungen von WhatsApp verstößt, und raten ausdrücklich von Massennachrichten, Spam, Stalkerware oder Überwachung von Personen ab. Für geschäftskritische Integrationen erwäge die offizielle WhatsApp Business API. Der beabsichtigte Anwendungsfall ist ein Unternehmen, das seinen eigenen Gesprächsverlauf analysiert.

Personenbezogene Daten: Der Chatverlauf sind personenbezogene Daten Dritter. Du bist allein dafür verantwortlich, eine gültige Rechtsgrundlage für die Verarbeitung zu haben und das für dich geltende Recht einzuhalten (DSGVO, LGPD, Ley 25.326, …). Die Verarbeitung erfolgt auf deiner eigenen Infrastruktur, und dieses Projekt überträgt nichts an seine Autoren. Der einzige ausgehende Datenfluss ist die Analysephase, die eine Korpus-Zusammenfassung an den von dir konfigurierten LLM-Anbieter sendet – bei einem lokalen oder Mock-Anbieter gar nichts. Wähle deinen Anbieter entsprechend.

Diese Software wird „AS IS“ ohne jegliche Gewährleistung bereitgestellt.

Related MCP server: Wasapi MCP Server

Warum der Verifizierer der eigentliche Kern ist

Diese Pipeline wurde für ein echtes Unternehmen gebaut: 11.782 Nachrichten, 610 Gespräche, 8 Monate Verlauf. Die LLM-Analyse erzeugte 60 Erkenntnisse über 7 Dimensionen. Dann durchlief jede Dimension einen unabhängigen Verifizierer, der jedes Zitat erneut lokalisierte und jede Behauptung gegen das Korpus nachzählte.

Der Verifizierer widerlegte 34 der 60 Erkenntnisse.

Plausible, gut geschriebene, selbstbewusst nummerierte Erkenntnisse – und mehr als die Hälfte davon überlebte den Kontakt mit den Daten nicht. Eine LLM-Analyse deines Unternehmens ohne Verifikationsdurchlauf ist keine Analyse; sie ist Fiktion mit hübscher Formatierung. Deshalb gilt in diesem Projekt:

• Jede Erkenntnis muss wörtliche Belege zitieren (thread_id + Zitat), und eine deterministische Code-Prüfung widerlegt jede Erkenntnis, deren Zitat nicht im Korpus existiert – kein Modell hat darüber eine Stimme;

• ein zweiter, unabhängiger LLM-Durchlauf zählt jede Häufigkeitsbehauptung neu und widerlegt, was nicht wie angegeben hält;

• das Schema macht das Urteil verpflichtend: Eine Analyse ohne aufgezeichneten Verifikationsdurchlauf ist konstruktionsbedingt ungültig;

• das Methodikblatt des Berichts druckt die widerlegten Erkenntnisse, damit niemand später die falschen Zahlen erneut zitiert.

Zwei Analyse-Linsen: kommerziell + FATE-verhaltensbezogen

Die Analyse wird mit zwei Dimensionssätzen geliefert, die beide derselben obligatorischen Verifikation unterliegen:

• Kommerziell (7 Dimensionen): echte FAQs, Antwortzeiten und Abläufe, Kundentypen, Produkte und Themen, Einwände und Reibungspunkte, Bot-Möglichkeiten, Ton und Stil.

• FATE-verhaltensbezogen (5 Dimensionen, npm run analyze -- --dimensions fate): wie das Unternehmen Aufmerksamkeit erregt (Focus), Sicherheit ausstrahlt und sein Wort hält (Authority), Kunden das Gefühl gibt, verstanden zu werden (Tribe), die emotionale Ebene erreicht statt Spezifikationen abzuladen (Emotion), und Kundenzustandssignale liest – nur Cluster, zuerst wohlwollende Erklärungen, Zustände, niemals Urteile über Einzelpersonen. Inspiriert vom FATE-Modell in Chase Hughes‘ The Behavior Ops Manual (eigene Darstellung; nicht verbunden mit oder unterstützt vom Autor). Befrage zuerst deinen Betreiber und füttere business-context.json – siehe analysis/PLAYBOOK.md.

In zwei Minuten ausprobieren (kein WhatsApp nötig)

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

Die Demo erzeugt ein synthetisches Korpus, startet einen Mock-WAHA-Server, führt die gesamte Pipeline dagegen aus (Probe → Export → Korpus → verifizierte Analyse → Bericht) mit einem Mock-LLM und hinterlässt den Bericht in out/demo/ in allen drei Formaten – XLSX (die Kunden-Tabelle), HTML (teilbare Einzeldatei) und DOCX (Word). Keine Schlüssel, kein Netzwerk, keine echten Daten.

Gegen dein echtes WhatsApp ausführen

Du benötigst eine laufende WAHA-Instanz mit verbundener Geschäftsnummer – siehe docs/waha-setup.md für die Fallstricke, die uns Tage gekostet haben (Engine-Wahl, fullSync, Geräteslots, @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

Möchtest du die Analyse lieber mit deinem eigenen Agenten (Claude Code, Cursor, was auch immer) statt der eingebauten Engine ausführen? Das ist ein erstklassiger Weg: analysis/PLAYBOOK.md.

Der offizielle-API-Pfad (Kapso)

Wenn die Nummer über die offizielle WhatsApp Business Platform durch Kapso läuft, überspringe WAHA vollständig – kein inoffizieller Client, kein ToS-Hinweis für diese Quelle, kein @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

Dasselbe Korpus, derselbe Verifizierer, dieselben Berichte. Ein ehrlicher Kompromiss: Die offizielle Plattform hat kein rückwirkendes Backfill, daher deckt der Verlauf ab, was seit der Verbindung der Nummer dort durch Kapso geflossen ist. Details und einen Mock-Server zum Ausprobieren ohne Konto: docs/kapso-setup.md.

Oder lass Claude das Ganze steuern (MCP)

npm run mcp startet einen MCP-Server, der Claude Desktop / Claude Code / ChatGPT / Cursor zur Audit-Engine macht: Der Agent interviewt dich, führt durch die WAHA-Einrichtung, zeigt den Pairing-QR direkt im Chat, exportiert den Verlauf und führt die Analyse selbst durch. Der Server hält es strukturell ehrlich – submit_dimension lehnt jede Dimension ohne aufgezeichnetes Verifikationsurteil ab, jedes Belegzitat wird serverseitig gegen das Korpus geprüft, und Chat-Inhalte werden als nicht vertrauenswürdige Daten behandelt. Er sendet niemals eine WhatsApp-Nachricht. Einrichtung: docs/mcp-setup.md.

Die 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

Jede Phase liest und schreibt einfache lokale Dateien (Standard data/wa-history/), sodass du jede Phase erneut ausführen kannst, ohne die vorherigen zu wiederholen – der Dump wird wegen eines Parsing-Fehlers nie erneut abgerufen.

Konfiguration

Kopiere wa-audit.config.json und bearbeite sie, oder verwende Umgebungsüberschreibungen (Umgebung gewinnt). Die Grundlagen:

Geheimnisse sind nur über Umgebung verfügbar: WAHA_BASE_URL, WAHA_API_KEY (+ ANTHROPIC_API_KEY oder LLM_API_KEY für Phase 4). WAHA_BASE_URL hat absichtlich keinen Standard – auf die falsche Instanz zu zeigen ist der teure Fehler.

Die Prosa des Berichts ist derzeit Spanisch (es-AR-Voreinstellung); der darunterliegende Datenvertrag ist Englisch. Prosa-i18n steht auf der Roadmap.

Datenvertrag

threads.json, summary.json und analysis.json sind versioniert (schema_version: 1) und dokumentiert in docs/data-contract.md. Der Analysevertrag ist formalisiert in analysis/analysis.schema.json (npm run check:analysis): Jede Engine, die gültiges analysis.json emittiert – LLM, Regeln, SQL, ein Mensch – wird ohne Änderungen in den Bericht eingebunden.

Ehrliche Einschränkungen

• Der Bulk-Verlaufsendpunkt von WAHA existiert nur auf den NOWEB/GOWS-Engines; WEBJS würde einen Chat-für-Chat-Export erfordern (hier nicht unterstützt – die Probe sagt es dir).

• Verlaufstiefe über ~3 Monate erfordert das Erstellen der Sitzung mit noweb.store.fullSync vor dem Dump (docs/waha-setup.md).

• Antwortzeit-Mediane verankern an der ersten Nachricht jedes eingehenden Bursts, und ausgehende Nachrichten unterscheiden nicht zwischen Menschen und Bots – beides im Methodikblatt des Berichts angegeben.

• Medien haben keinen analysierbaren Text (downloadMedia=false): Fotos und Sprachnotizen erscheinen getippt, aber leer.

• xlsx@0.18.5 (festgepinnt: die Stil-Nachbearbeitung hängt davon ab) hat eine bekannte Upstream-Warnung (Prototype Pollution / ReDoS auf nicht vertrauenswürdigen Tabellenkalkulationen). Dieses Projekt schreibt nur XLSX und liest seine eigene Ausgabe zurück, daher greift der Vektor nicht – aber npm audit wird es melden, und wir sagen es dir lieber, als es zu verstecken.

• Die XLSX-Stilgestaltung funktioniert durch Nachbearbeitung der Datei als ZIP – absichtliche, dokumentierte schwarze Magie: docs/xlsx-postprocess.md.

Entwicklung

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)

Alles in fixtures/ ist synthetisch und erfunden. Kein echtes Gespräch, keine echte Telefonnummer oder Name eines tatsächlichen Unternehmens existiert in diesem Repository.

Lizenz

MIT.