WhatsApp Intelligence Dashboard

A unified web interface for browsing WhatsApp chats, messages, contacts, and transcribing audio files. Integrates the WhatsApp Bridge, MCP server, and VoiceScript transcription service.

It also includes a Gemini-powered autonomous "brain" that can review recent incoming messages every 5 minutes, apply labels through MCP, create Google Tasks through MCP, and save draft replies into Supabase for approval.

Architecture

┌─────────────────────────────────────────────────────┐
│        WhatsApp Intelligence Dashboard              │
│  (Express.js server + HTML/JS frontend)             │
├─────────────────────────────────────────────────────┤
│  REST API Endpoints:                                │
│  ├─ /api/health           (status check)            │
│  ├─ /api/contacts/*       (search & manage)         │
│  ├─ /api/chats/*          (browse & view)           │
│  ├─ /api/messages/*       (list, context, send)     │
│  └─ /api/transcribe       (proxy to VoiceScript)    │
├─────────────────────────────────────────────────────┤
│                     ↓                               │
│  ┌──────────────────────────────────────────────┐  │
│  │  WhatsApp MCP Server (Python stdio)          │  │
│  │  └─ 11+ tools: search_contacts, send_message,│  │
│  │    download_media, etc.                      │  │
│  └──────────────────────────────────────────────┘  │
│                     ↓                               │
│  ┌──────────────────────────────────────────────┐  │
│  │  WhatsApp Bridge (Go) + SQLite DB            │  │
│  │  └─ Syncs chats, messages, contacts          │  │
│  └──────────────────────────────────────────────┘  │
│                                                     │
│  ┌──────────────────────────────────────────────┐  │
│  │  VoiceScript Express (Port 3000)             │  │
│  │  └─ POST /transcribe (audio → text)          │  │
│  │  └─ GET /health                              │  │
│  └──────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

Prerequisites

1. WhatsApp Bridge running and authenticated

   cd whatsapp-bridge
   go run main.go
   # Scan QR code to authenticate

2. Python 3.10+ and uv (installed for MCP server)

   python --version
   which uv  # or where uv on Windows

3. VoiceScript Express running with Azure Whisper credentials

   cd WA_VoiceScript
   npm install
   cp .env.example .env
   # Fill in AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_KEY
   npm start

4. Node.js 18+ for the dashboard

   node --version
   npm --version

Setup

1. Install Dependencies

cd dashboard
npm install

2. Configure Environment

cp .env.example .env

Edit .env if your paths differ:

• PORT - Dashboard port (default 4000)
• MCP_SERVER_PATH - Path to uv.exe
• MCP_CWD - Path to whatsapp-mcp-server directory
• VOICESCRIPT_URL - VoiceScript server URL (default http://localhost:3000)
• GEMINI_API_KEY - Google Gemini API key for the autonomous brain
• SUPABASE_URL - Supabase project URL
• SUPABASE_ANON_KEY - Supabase anon key used to store processed messages and reply drafts

3. Start Dashboard

npm start
# or for development with auto-reload:
npm run dev

The dashboard will be available at http://localhost:4000

Usage

Chats Tab

Browse all WhatsApp chats and view details:

• Search: Find chats by name
• Select: Click a chat to view details
• Load Messages: View messages in selected chat

Messages Tab

Search and view messages with context:

• Search: Find messages by content
• Select: Click a message to see surrounding conversation
• Context: View 3 messages before/after selected message

Contacts Tab

Search and message contacts:

• Search: Find contacts by name or phone
• View Details: Contact JID and message interface
• Send Message: Type and send WhatsApp message

Transcribe Audio Tab

Convert audio files to text:

• Upload File: Select .opus, .ogg, .wav, .mp3, .m4a, etc. (up to 25 MB)
• Speaker Label (optional): Identify speaker for context
• Transcribe: Send to Azure Whisper for processing
• Actions:
  • Copy transcript to clipboard
  • Download as .txt file
  • Send as WhatsApp message (requires contact selected)

API Endpoints

Health & Status

• GET /api/health - Server status and connectivity

Chats

• GET /api/chats?query=...&limit=20&sort_by=last_active - List chats
• GET /api/chats/:jid - Get specific chat metadata

Contacts

• GET /api/contacts/search?query=... - Search contacts

Messages

• GET /api/messages?chat_jid=...&query=...&limit=20 - List messages
• GET /api/messages/:id/context?before=5&after=5 - Get context around message
• POST /api/messages/send - Send message
  • Body: { "recipient": "...", "message": "..." }

Media

• POST /api/media/download - Download media from message
  • Body: { "message_id": "...", "chat_jid": "..." }

Transcription

• POST /api/transcribe - Transcribe audio file
  • Form data: audio (multipart file)
  • Response: { "transcript": "..." }

Troubleshooting

MCP Server Won't Start

• Verify Python is installed and in PATH: python --version
• Verify uv is installed: uv --version
• Check MCP_CWD path in .env is correct
• Try running MCP manually:

  cd <MCP_CWD>
  uv run python main.py

Can't Connect to WhatsApp

• Ensure WhatsApp Bridge is running
• Check if it's still authenticated or needs QR code re-scan
• Check SQLite database exists at whatsapp-bridge/store/whatsapp.db

VoiceScript Not Found

• Ensure VoiceScript is running on port 3000
• Check VOICESCRIPT_URL in .env
• Verify Azure credentials are set in VoiceScript .env

Messages Not Loading

• Sync WhatsApp by navigating in WhatsApp Web for 30 seconds
• Check Bridge sync logs for errors
• Verify SQLite database permissions

Development

Running in Development Mode

npm run dev

This uses nodemon to auto-reload the server on file changes.

Frontend Architecture

• Tabs: Chats, Messages, Contacts, Transcribe Audio
• Two-Column Layout:
  • Left sidebar: Lists (chats, messages, contacts)
  • Right area: Details and actions
• Responsive: Mobile-friendly collapsible layout
• Real-time: No polling — instant API requests on user action

Adding New Features

1. New MCP Tool:

   • Add REST endpoint in server.js
   • Add UI component in public/index.html
   • Call callMcpTool(toolName, args) to invoke

2. New API Endpoint:

   • Add Express route in server.js
   • Optionally wrap MCP tool calls
   • Test with curl or frontend

Autonomous Brain

• Runs every 5 minutes using node-cron
• Pulls the latest WhatsApp messages through list_messages
• Uses Gemini structured JSON output to decide whether to:
  • create a draft reply
  • create Google Tasks through MCP
  • apply a chat label through MCP
  • ignore personal/family chats
• Stores processed message IDs in Supabase table processed_messages
• Stores pending AI drafts in Supabase table message_drafts

Notes

• Transcripts are stored in browser localStorage under key voicescript_transcripts
• All media downloads go to the system temp directory (auto-cleaned)
• MCP server process runs as child process — restarts if crashes
• Requires WhatsApp Bridge to be authenticated first

License

See parent project LICENSE