WhatsApp-Pi

A WhatsApp integration extension for the Pi Coding Agent.

Pi is a powerful agentic AI coding assistant that operates in your terminal. This extension lets you chat and pair-program with your Pi agent through WhatsApp, with message filtering, allowed contacts/groups, recents/history browsing, message detail/reply, group-only binding, and reliable message delivery.

Features

• Manual WhatsApp Connection: QR code-based authentication with session persistence
• Allowed Contacts: Control which phone numbers can interact with Pi
  • Add contacts with optional names for easy identification
  • View ignored numbers (not yet allowed) and add them when needed
  • Manage aliases and print allowed contacts from the menu
• Allowed Groups: Control which WhatsApp groups can interact with Pi
  • Add group JIDs with optional aliases
  • Only groups in Allowed Groups are processed by the agent
• Recents & History: Browse recent conversations, inspect full message history, and reply from message detail view
• Reliable Messaging: Queue-based message sending with retry logic
• TUI Integration: Menu-driven interface for managing connections, contacts, and recent chats
• Group-Only Mode: Bind the agent to a single WhatsApp group with --whatsapp-group
• Media Support:
  • Vision Analysis: Automatically forwards WhatsApp images to Pi for analysis.
  • Audio Transcription: Transcribes voice notes locally with Whisper.cpp (whisper-cpp-node); ffmpeg is used to convert WhatsApp audio to 16 kHz mono WAV first.
  • Document Handling: Downloads and stores documents (PDF, text) for agent access; PDFs include a bounded text preview when readable.

Prerequisites

Pi Coding Agent

Install Pi from pi.dev:

Linux / macOS (recommended):

curl -fsSL https://pi.dev/install.sh | sh

Or via npm (requires Node.js 20+):

npm install -g @earendil-works/pi-coding-agent

Then authenticate or set an API key before starting:

# Use /login inside Pi for subscription providers, or set an API key:
export ANTHROPIC_API_KEY=sk-ant-...
# OpenAI
export OPENAI_API_KEY=sk-...
# Google Gemini
export GEMINI_API_KEY=...

See the Pi documentation for full setup, providers, and model configuration details.

Audio Transcription

Audio transcription uses whisper-cpp-node and ffmpeg.

Install dependencies:

npm install

Make sure ffmpeg is available in PATH.

PDF documents are parsed locally and do not require extra system utilities. If a PDF cannot be parsed automatically, it is still saved and forwarded with a clear fallback notice.

Quick Start

1. Install the extension:

pi install npm:whatsapp-pi

2. Start Pi:

pi

3. Open /whatsapp and choose Connect / Reconnect WhatsApp.

   • QR appears only on first pair or after logoff.

4. Add the chat you will use with Pi to Allowed Contacts or Allowed Groups.

5. Send a message from that allowed chat to Pi.

   • Pi replies in same thread.
   • Use Recents only to browse history or reply manually.

After first pairing, you can start Pi with auto-connect enabled:

pi --whatsapp-pi-online

Development / Testing

If you are developing or testing the extension locally, you can clone the repository from GitHub:

1. Clone and install dependencies:

git clone https://github.com/RaphaCastelloes/whatsapp-pi.git
cd whatsapp-pi
npm install

2. Run the extension:

pi -e whatsapp-pi.ts

For verbose mode (shows Baileys trace logs and audio timing logs for debugging):

pi -e whatsapp-pi.ts --verbose

To test startup auto-connect locally after you have already paired WhatsApp:

pi -e whatsapp-pi.ts --whatsapp-pi-online

How It Works

• Pi processes incoming messages only from allowed contacts or allowed groups.
• Recents is history browser, not trigger.
• Send Message and send_wa_message are outbound only.
• If you message yourself, WhatsApp may show sent/read ticks, but that does not guarantee Pi will treat it as a trigger.

LLM-Callable Tools

The extension registers the following tools that the Pi agent can call:

Tool	Direction	Description
send_wa_message	outbound	Send a WhatsApp message to a contact or group (or reply to the last conversation if jid is omitted).
send_reaction	outbound	React to a WhatsApp message with an emoji.
list_wa_conversations	read-only	List recent conversations from the local recents store. Supports onlyIncoming, onlyAllowed, and limit.
get_wa_conversation_history	read-only	Get the most recent messages with a given senderNumber (accepts +E164, raw digits, or a JID). Supports limit.
check_wa_new_messages	read-only	List conversations whose most recent message is incoming (i.e. waiting for a reply). Supports sinceTimestamp (ms epoch).

The three read-only tools query the local recents store at ~/.pi/agent/extensions/whatsapp-pi/recents/recents.json. They never touch the network and do not mark messages as read.

WhatsApp Numbers and JIDs

• Contacts use phone format in UI: +5511999999999
• Internally, contacts map to JIDs like 5511999999999@s.whatsapp.net
• Groups use JIDs like 120363012345@g.us
• Recents may show normalized values from WhatsApp, so use Print Contact / Print Group JID and aliases to avoid confusion.

Commands

• /whatsapp - Open the WhatsApp management menu

Main Menu Options

• Connect / Reconnect WhatsApp - Start WhatsApp connection using saved credentials when available; QR code appears only if pairing is required
• Disconnect WhatsApp - Stop WhatsApp connection
• Logoff (Delete Session) - Remove all credentials and session data
• Recents - Open recent conversations, view history, and reply
• Allowed Contacts - Manage contacts that can interact with Pi
• Allowed Groups - Manage WhatsApp groups that can interact with Pi

Allowed Contacts Management

• Add Contact - Add a new contact to the allowed contacts list (format: +5511999999999)
• Select a contact - Open a submenu with History, Send Message, Print Contact, Add Alias, Remove Alias, Add Number, Remove Number, Remove Contact, and Back
• Back - Return to main menu

Allowed Groups Management

• Add Group - Add a WhatsApp group JID to the allowed groups list (format: 120363012345@g.us)
• Select a group - Open a submenu with History, Send Message, Print Group JID, Add Alias, Remove Alias, Remove Group, and Back

Recents Management

• History - Open full message history for that conversation
• Send Message - Send a new message without Pi suffix
• Reply - Open message detail, then press R to reply
• Allow Contact / Allow Group - Move a recent sender into the appropriate allowed list
• Remove Alias - Clear saved alias for that sender
• Back - Return to main menu

WhatsApp Chat Commands

Send these commands directly in WhatsApp to control the agent session:

• /compact - Compact the current Pi session context
• /abort - Abort the current Pi agent operation

Project Structure

src/
├── services/        # Core services (WhatsApp, Session, Recents, Media)
└── ui/              # Menu handlers and TUI views

tests/
└── unit/            # Unit tests

Development

Run tests:

npm test

Notes

• --whatsapp-pi-online auto-connects when credentials already exist.
• --whatsapp-group <jid> binds Pi to one WhatsApp group.
• Media handling is local: images for vision, audio via Whisper.cpp + ffmpeg, documents stored under .pi-data/whatsapp/documents/.
• Recents/history live in ~/.pi/agent/extensions/whatsapp-pi/recents/recents.json.
• Session state, allow lists, and startup reconnects are persisted locally.