docs(spec): add WhatsApp messaging adapter evaluation and decision document

Signed-off-by: theonlychant <sacehenry@gmail.com>

Author: theonlychant

docs/issues/phase1-whatsapp-implementation.md

@@ -0,0 +1,48 @@
+# Phase 1: WhatsApp Integration — Implementation Proposal
+
+Status: draft
+Related: docs/spec/whatsapp-evaluation.md, issue #889 (Telegram Phase 0)
+
+Objective
+- Produce a scoped Phase 1 implementation that validates feasibility and produces a production-ready adapter design for WhatsApp using the chosen path.
+
+Decision (from evaluation)
+- Preferred production path: WhatsApp Business Cloud API via a partner (Twilio or 360dialog). If no commercial funding / business justification, defer until after v0.20.0.
+
+Scope (what this PR will do)
+- Implement a `whatsapp` messaging adapter for GAIA that:
+  - Registers a partner-backed transport (Twilio/360dialog) with config-driven credentials.
+  - Translates incoming webhooks into GAIA adapter events (message, media, reaction, read receipts).
+  - Sends replies via partner API including media uploads.
+  - Handles template message sending for proactive outbound workflows.
+  - Includes unit tests for adapter mapping and an integration smoke test (manual-run) guide.
+
+Out of scope
+- Supporting community drivers (`whatsapp-web.js`, Baileys) in the same PR; these remain experimental spikes.
+- Automating Meta Business verification or partner account creation.
+
+Phase 1 tasks (concrete)
+1) Onboarding docs & credentials (owner: PM) - start Meta Business verification and partner account setup; document expected timelines. (3–7d external)
+2) Adapter skeleton (owner: eng) - implement webhook handling, auth, and event mappings; unit tests. (3–5d)
+3) Template workflow (owner: eng) - implement template send path and test harness for approved templates. (2–4d)
+4) Media handling (owner: eng) - media upload/download flow via partner. (2–4d)
+5) Integration spec & docs (owner: eng/pm) - docs/spec/whatsapp-evaluation.md link, configuration docs, runbook for rate-limiting and errors. (2d)
+6) Spikes (parallel):
+   - Spike A: whatsapp-web.js prototype (safety spike) - 2–3d, document ban-rate and operational risks.
+   - Spike B: Business Cloud API free-tier onboarding trial - 3–5d, document verification friction and webhook round-trip.
+
+Acceptance criteria
+- Adapter code checked in under `src/gaia/` with unit tests.
+- Documentation updated: `docs/spec/whatsapp-evaluation.md` and adapter README with setup steps.
+- Spike reports for A/B filed under `docs/spikes/whatsapp-webjs.md` and `docs/spikes/whatsapp-cloudapi.md` (manual deliverables).
+
+Risks
+- Long external wait times (Meta verification) - mitigate by starting verification early and running local integration tests with partner sandbox numbers.
+- Privacy contractual review required before storing message logs - involve legal.
+
+Estimates
+- Implementation (adapter + tests + docs): 2–3 engineer-weeks.
+- Spikes & onboarding: 1–2 engineer-weeks (parallelizable).
+
+Next steps
+- Confirm path (partner vs. defer). If confirmed, assign engineer and PM, start partner onboarding, and open a scoped implementation PR with the adapter skeleton.

docs/spec/whatsapp-evaluation.md

@@ -0,0 +1,94 @@
+# WhatsApp Evaluation — Decision Document
+
+Status: draft
+Date: 2026-05-03
+
+Summary
+- Goal: evaluate WhatsApp as a messaging surface for GAIA and recommend a Phase 1 path (integration/not-ready/deferral).
+- Short recommendation: For Phase 1, pursue the WhatsApp Business Cloud API via a partner (Twilio or 360dialog) **only if** we can justify the cost and business verification friction; otherwise defer WhatsApp until post-v0.20.0 and focus on Telegram for Phase 0.
+
+Integration paths (concrete pros/cons)
+
+1) WhatsApp Business Cloud API (Meta-hosted)
+  - Pros:
+    - Official, supported API with predictable behaviour and low ban risk.
+    - Scales to many users and supports media messages, templates, and webhooks.
+    - Legal / terms-of-service alignment - suitable for production.
+  - Cons:
+    - Requires Business Manager verification, a phone number, and template approval for outbound messages.
+    - Conversations are template-gated for initial outbound messages (session vs template model) which constrains UX for unsolicited streaming or voice-first flows.
+    - Metadata and message content transit Meta servers - privacy implications.
+
+2) WhatsApp Business API via partners (Twilio, 360dialog, MessageBird)
+  - Pros:
+    - Polished onboarding, SDKs, billing, and delivery guarantees; some partners reduce Meta verification friction.
+    - Single integration point with enterprise-grade features (message queues, retries, logging).
+  - Cons:
+    - Adds third-party vendor costs and another privacy/metadata recipient.
+    - Still subject to Meta template rules; partner doesn't eliminate wrapper constraints.
+
+3) whatsapp-web.js (community library driving WhatsApp Web)
+  - Pros:
+    - Works with personal accounts, quick to prototype, free software (MIT).
+    - Enables features not available via Business API (ad-hoc messages, voice notes from personal threads) and can be run locally.
+  - Cons:
+    - Violates WhatsApp Terms of Service for automated non-official clients; accounts are commonly banned.
+    - Unreliable long-term: session invalidation, frequent breakages when WhatsApp updates Web protocol.
+    - Metadata still goes to Meta (via Web client) - plus our client holds session credentials.
+
+4) Baileys (reverse-engineered protocol)
+  - Pros: low-level control, performant, community-maintained, avoids Puppeteer overhead.
+  - Cons: same TOS risk as whatsapp-web.js; higher maintenance; frequent breakage after protocol changes.
+
+Privacy posture (which servers see message data / metadata)
+- Business Cloud API: Message payloads and metadata flow through Meta Cloud API endpoints (Meta-managed infra). If using a partner, message copies / delivery metadata also flow through the partner's servers.
+- Partner (Twilio/360dialog): Partner sees metadata and possibly message bodies (depending on partner model). They store logs/delivery receipts per contract.
+- whatsapp-web.js / Baileys: Messages flow end-to-end between participants but are proxied through Meta (WhatsApp Web). Our local client holds session keys; Meta still sees metadata (device/IP) and may analyze content per their privacy policy. Because these are unofficial clients, WhatsApp monitors for automation patterns and may ban accounts.
+
+Cost model (production)
+- Business Cloud API (Meta): Meta pricing varies and often has free tier for limited messages; template messages may have per-message charges in some regions. Expect low per-message cost but operational overhead (verification) and possible per-message charges for large campaigns.
+- Partner (Twilio): Typical model is per-message + monthly number fees + optional throughput/queueing. Budget: modest monthly fixed + per-message variable (example: $0.005–$0.05/msg depending on region and message type).
+- whatsapp-web.js / Baileys: Zero direct provider fees, but higher maintenance cost and risk (replace suspended accounts, dev time). Not viable for reliable production.
+
+UX implications vs Telegram (side-by-side)
+- Message templates + session model (WhatsApp Business) make unsolicited streaming (e.g., long TTS or progressive voice notes) awkward: initial outbound must be a pre-approved template in many cases, while Telegram allows free-form message delivery and bot-initiated rich interactions.
+- Voice notes: WhatsApp supports voice messages natively, but streaming partial audio to render progressive playback is not supported by Business Cloud API — we'd need to upload final audio or use ephemeral media sessions. Telegram supports bots sending audio and streaming-like behaviours more easily.
+- Presence and discoverability: WhatsApp relies on phone numbers and a business profile; Telegram bots have usernames and deep-linking that are easier for consumer discovery and opt-in.
+
+Recommended Phase 1 path and rationale
+- Recommendation: Defer unlimited WhatsApp integration until post-v0.20.0 unless there is a funded business case requiring WhatsApp immediately. If we must ship Phase 1, target the **WhatsApp Business Cloud API via a partner (Twilio or 360dialog)** as the implementation path for production-grade users. Rationale:
+  - Official APIs + partner tooling reduce ban/legal risk and provide production SLAs.
+  - Although template gating reduces some UX flexibility, a partner + careful conversation design can deliver acceptable UX for business use-cases (support agents, notifications, private assistant flows initiated by users).
+  - Avoid community drivers for Phase 1 due to high ban risk and maintenance burden.
+
+Sample conversation (Business Cloud via partner)
+User -> GAIA: "Hey, summarize my travel plan for May 11"
+GAIA -> (incoming webhook) -> agent resolves intent and replies as a session message (no template needed if user initiated within 24h). If GAIA needs to proactively message later, it uses an approved template: "Your travel summary is ready: [link]".
+
+Setup steps (partner-assisted Phase 1)
+1. Create Meta Business Manager, complete verification (documented; can take days).
+2. Provision WhatsApp Business account and phone number (via Twilio/360dialog).
+3. Configure webhooks to GAIA's API server (TLS endpoint), map partner events to `gaia` adapter.
+4. Implement conversation mapping: webhook -> adapter -> agent -> reply via partner API.
+5. Submit required message templates for proactive messages.
+
+Phase 1 investigation tasks & effort estimate
+- Spike A — whatsapp-web.js prototype (safety spike): 2–3d engineer. Deliverable: short-running prototype, documented ban-rate evidence (public threads & maintainers), and a decision note explaining operational risk.
+- Spike B — Business Cloud API free-tier onboarding: 3–5d engineer (mainly procedural). Deliverable: documented steps, expected Meta verification time, sample webhook round-trip, template submission trial.
+- Design task — UX mapping vs Telegram: 1–2d PM/Designer to map conversational flows and constraints (template gating, voice notes, streaming). Deliverable: side-by-side UX matrix and concrete recommendations.
+- Integration spec — Partner integration adapter + auth + message mapping: 3–5d engineer to draft Phase 1 implementation PR scope and API shapes.
+- Total Phase 1 investigation estimate: 2–3 weeks (one engineer + PM part-time).
+
+Risks & mitigations
+- Account bans (web.js/Baileys): risk -> avoid for Phase 1.
+- Long Meta verification times: mitigation -> use partner onboarding guidance and start process early, budget for delays.
+- Privacy concerns: mitigate via docs, opt-in flows, minimal logging, and contractual review with partners.
+
+Decision outcome & next steps
+- Primary choice: Defer or build on Business Cloud API via partner. Phase 1 should focus on investigation spikes and a partner-backed adapter if the project has commercial justification.
+- Next steps (Phase 1): run Spike A and Spike B in parallel, finalize integration spec, then open implementation PR scoped to partner adapter + tests + docs.
+
+Links and references
+- WhatsApp Business Cloud API: https://developers.facebook.com/docs/whatsapp
+- whatsapp-web.js: https://github.com/pedroslopez/whatsapp-web.js
+- Baileys: https://github.com/WhiskeySockets/Baileys

docs/spikes/whatsapp-cloudapi.md

@@ -0,0 +1,26 @@
+# Spike B - WhatsApp Business Cloud API onboarding trial
+
+Status: in-progress
+Owner: engineering / PM
+Start date: 2026-05-03
+
+Objective
+- Attempt the Business Cloud API free-tier onboarding and verify webhook round-trip, template submission, and expected Meta business verification friction.
+
+Success criteria
+- Able to register a test WhatsApp Business Account (or provision via partner sandbox), register a webhook, and send/receive a test message.
+- Document time-to-verify for Business Manager and template approval steps.
+
+How to run the trial (high level)
+1. Create a Meta Business Manager account and begin verification (requires legal company info).
+2. Option A: Use direct Business Cloud API sandbox (if available) — follow Meta docs.
+3. Option B (recommended for Phase 1): Provision a partner sandbox (Twilio/360dialog) with a test number and follow their webhook docs.
+4. Configure a TLS endpoint to receive webhooks from partner / Meta and map to GAIA adapter.
+
+Notes
+- Meta verification can take days; partners often streamline onboarding and provide sandbox/test numbers.
+- Templates must be submitted and approved for proactive outbound messages; this step can also take time.
+
+Deliverables
+- `docs/spikes/whatsapp-cloudapi.md` (this doc, updated with findings)
+- Short onboarding log with screenshots and time estimates.

docs/spikes/whatsapp-webjs.md

@@ -0,0 +1,43 @@
+# Spike A - whatsapp-web.js prototype
+
+Status: in-progress
+Owner: engineering
+Start date: 2026-05-03
+
+Objective
+- Build a minimal prototype using `whatsapp-web.js` to confirm: connection flow, message send/receive, media handling, and measure ban/instability signals over short runs.
+
+Success criteria
+- Can connect to a personal WhatsApp account and receive/send messages programmatically.
+- Produce a short log of breakages, session invalidations, or bans over a 48–72h window (if feasible).
+- Produce a brief operational risk note summarizing public ban-rate signals from maintainers and GitHub issues.
+
+How to run the prototype (manual steps)
+1. Prepare a dedicated test phone + WhatsApp account (not a primary personal account).
+2. On a machine with Node.js (16+), run:
+
+```bash
+cd experiments/whatsapp-webjs
+npm install
+node index.js
+```
+
+3. Scan the QR code with the test phone (the script prints a QR to the terminal).
+4. Send messages to the account and observe logs.
+
+Initial run notes
+- I started the prototype and it printed the QR to the terminal; you scanned it and the script accepted the handshake payload. The process was interrupted with Ctrl+C (exit code 130) during the manual run - see `experiments/whatsapp-webjs/run.log` for recorded events.
+- Puppeteer required native Chromium libraries; on Debian/Ubuntu install `libnss3`, `libnspr4`, `libgtk-3-0`, etc. before running.
+
+Next steps for the spike
+- Keep the prototype running on a sacrificial test account for 24–72h and record any `disconnected`, `auth_failure`, or account ban signals in `run.log`.
+- Collect public evidence: search maintainer issues and community threads for ban-rate anecdotes and link findings in this doc.
+
+Notes and warnings
+- This uses an unofficial client that automates WhatsApp Web; using it for automation is against WhatsApp's TOS and accounts do get banned. Use a sacrificial test account and do not use production / personal numbers.
+- Keep runs short and document any account suspensions. Do not publish account credentials.
+
+Deliverables
+- `experiments/whatsapp-webjs` prototype scaffolding (index.js, package.json).
+- `docs/spikes/whatsapp-webjs.md` — this doc (updated with findings).
+- Short report capturing observed instability and references to public threads.

experiments/whatsapp-webjs/index.js

@@ -0,0 +1,61 @@
+const { Client, LocalAuth } = require('whatsapp-web.js');
+const qrcode = require('qrcode-terminal');
+const fs = require('fs');
+const path = require('path');
+
+const LOG_PATH = path.resolve(__dirname, 'run.log');
+function writeLog(...parts) {
+  const line = `[${new Date().toISOString()}] ${parts.join(' ')}\n`;
+  process.stdout.write(line);
+  try {
+    fs.appendFileSync(LOG_PATH, line);
+  } catch (e) {
+    // ignore logging errors
+  }
+}
+
+// Minimal prototype: prints QR, logs incoming messages, echoes them back.
+const client = new Client({ authStrategy: new LocalAuth() });
+
+client.on('qr', (qr) => {
+  qrcode.generate(qr, { small: true });
+  writeLog('EVENT qr');
+});
+
+client.on('authenticated', (session) => {
+  writeLog('EVENT authenticated');
+});
+
+client.on('auth_failure', (msg) => {
+  writeLog('EVENT auth_failure', msg);
+});
+
+client.on('ready', () => {
+  writeLog('EVENT ready');
+});
+
+client.on('disconnected', (reason) => {
+  writeLog('EVENT disconnected', reason);
+});
+
+client.on('message', async (msg) => {
+  writeLog('IN', msg.from, msg.body);
+  try {
+    await msg.reply('Echo: ' + msg.body);
+    writeLog('OUT reply', msg.from);
+  } catch (e) {
+    writeLog('ERROR reply', e && e.message);
+  }
+});
+
+process.on('SIGINT', async () => {
+  writeLog('SIGINT received — shutting down');
+  try {
+    await client.destroy();
+  } catch (e) {
+    // ignore
+  }
+  process.exit(0);
+});
+
+client.initialize();