parley

One line to install on any machine:

# Windows (PowerShell) — runs the installer: install + enable the port + next steps
irm https://raw.githubusercontent.com/Sachitt-AV-08/parley/main/install.ps1 | iex

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Sachitt-AV-08/parley/main/install.sh | sh

The installer detects uv → pipx → pip, installs parley-wa[mcp] (CLI and MCP extras) from the latest GitHub Release (sha256 checksums included), and prints next steps. pip install 'parley-wa[mcp]' works once the PyPI publish lands; until then use the installer or a release wheel URL. Run parley setup manually to enable the debugging port.

One line to send from a script on any machine:

# Use the installer (recommended):
irm https://raw.githubusercontent.com/Sachitt-AV-08/parley/main/install.ps1 | iex   # Windows
curl -fsSL https://raw.githubusercontent.com/Sachitt-AV-08/parley/main/install.sh | sh   # macOS/Linux

# Or with a release wheel URL:
pip install 'parley-wa[mcp] @ https://github.com/Sachitt-AV-08/parley/releases/download/v0.3.2/parley_wa-0.3.2-py3-none-any.whl'
parley setup            # enable the local debugging port (auto-undoable)
parley send --to Ava --text "ci is green"   # resolves Ava -> live chat -> sends -> confirms it landed

Or in Python:

from parley import Session, parley_connect

wa = parley_connect()            # auto-attaches to the running WhatsApp Desktop
wa.send("Weekend Hikers", "who's bringing the snacks?")
for chat in wa.chats(unread_only=True):
    print(chat)

No WhatsApp account? The entire API runs on a fully scripted simulator:

parley --demo status
parley --demo send --to Ava --text "hi from parley"
parley --demo tui

Threat model

parley works by enabling WebView2's remote debugging port. While it's enabled, any process running as your user can drive your logged-in WhatsApp session and read all chats. parley does not add auth to that port; it is a local-machine trust boundary. If that's not acceptable for your machine, don't run parley setup.

Mitigations: run parley setup --undo when not in use; the HTTP API requires a token and rejects browser origins; the MCP server is read-only unless --allow-send is set; scheduled sends honor the same human pacing budget. Not covered: malware already running as your user; untrusted content in chats (prompt injection) if you give an agent send access.

Related MCP server: waxum-mcp

Features

--to knows people and groups: pass an id (15551234567@c.us), a bare number (+1 555 123 4567), a contact name (Ava) or a group subject (Weekend Hikers) — parley finds the exact chat, opens it, verifies the header and only then types. No wrong-chat accidents.

Quick tour

# enable the debugging channel (undo later with: parley setup --undo)
parley setup            # user-level env var, no admin; add --admin for HKLM
parley doctor           # confirm: process running? flag present? endpoint open?

# your real install:
parley chats
parley send --to "Weekend Hikers" --text "who's bringing the snacks?"
parley send --to "+91 98765 43210" --text "sms alternative, but over WhatsApp"
parley chat Ava --json | jq '.[0]'

# scheduled + recurring sends, right from the API:
parley schedule add --to Ava --text "morning standup reminder" \
    --at "2026-10-02T09:00:00" --repeat daily
parley schedule list
parley schedule run --once                # fire anything due, right now

# any HTTP client can use it too — `parley server` issues a token on first
# run and prints it (see `~/.parley/server.token`); pass it as a Bearer token:
export PARLEY_TOKEN="$(cat ~/.parley/server.token)"
curl -X POST localhost:8300/send -H "content-type: application/json" \
     -H "authorization: Bearer $PARLEY_TOKEN" \
     -d '{"to":"Ava","text":"via http"}'

Every command supports --json for piping into scripts, agents and cron. Scheduled entries live in ~/.parley/schedules.json (override with PARLEY_DATA_DIR), and parley server watches the queue in the background — a scheduled send obeys the same pacing and budget as a manual send.

Status

The live-store APIs are inherently version-sensitive (they call WhatsApp's own internal module surface). parley degrades gracefully — a build bump only ever softens a feature, never crashes the process.

Documentation

• Architecture — CDP attach, Store vs DOM, pacing, scheduler

• MCP Integration — stdio server, read-only default, --allow-send, PARLEY_ALLOW_TO

• Reliability — three-step verification, timing benchmarks

• Comparison — vs Cloud API, scrapers, cloud platforms

• Human Pacing — typing, network jitter, burst budget

• Safety — local-only, paced, terms, loopback

• Detailed Status — full feature matrix

• Roadmap — PyPI, media, webhooks, container mode

• Contributing — dev setup, CI, reporting

• License — MIT, contributors

Contributors

• Sachitt (@Sachitt-AV-08) — creator, maintainer

License

MIT © Sachitt. Made for people who automate their own machines — not for harvesting other people's. See LICENSE.