WPP_Whatsapp

WhatsApp Web automation for Python, built on WPPConnect and WA-JS, using Playwright.

Documentation · Español · PyPI · Releases

Install

The core supports Python 3.9+. FastMCP support requires Python 3.10+.

python -m pip install --upgrade WPP_Whatsapp
python -m pip install --upgrade "WPP_Whatsapp[mcp]"

The second command adds the optional MCP server. For a source checkout, use python -m pip install -e ".[mcp,dev]". Chrome is used by default; see installation for Playwright Chromium and optional FFmpeg/stealth.

Synchronous client

Create is a factory. start() or entering its context returns the Whatsapp client; register callbacks on that client.

from threading import Event
from WPP_Whatsapp import Create

with Create(session="mybot", autoClose=0) as client:
    def incoming(message):
        print("Received message ID:", message.get("id"))

    client.onMessage(incoming)
    print("Listening; press Ctrl+C to close.")
    Event().wait()

Scan the QR in the browser. The saved profile is reused on the next run. Context exit closes owned resources; it does not log the account out.

Native asyncio

import asyncio
from WPP_Whatsapp import AsyncClient

async def main():
    async with AsyncClient("mybot", autoClose=0) as client:
        chats = await client.chats.list_chats({"count": 10})
        print("Chats loaded:", len(chats))

asyncio.run(main())

Use one client from its owning event loop. Native services use snake_case; legacy flat methods retain their names and raw return values. Tracked service sends return delivery receipts; a confirmed ID does not prove delivery/read. See API examples and the migration guide.

FastMCP server

wpp-whatsapp-mcp --session mybot
wpp-whatsapp-mcp --session mybot --transport http --port 8765

Choose one command: the first uses stdio, the second exposes http://127.0.0.1:8765/mcp. Starting the server does not start WhatsApp. Call whatsapp_connect, log in in the browser, then poll whatsapp_status until ready.

Version 2.2.0 provides 21 tools, adding account isolation, bounded search, incoming events, diagnostics, replies and tracked media to the original 2.1.0 tools. --read-only leaves 16 tools. Account policies use verified JWT identity/scopes; each configured account has its own profile, delivery ledger and event buffer. See FastMCP configuration and delivery semantics.

Opt-in typed reads, diagnostics and bounded media are available from 2.2.0 without changing legacy raw results. Version 2.1.0 has the original 12 tools.

Runtime, sessions and compatibility

Bundled assets: WPPConnect 2.3.4, WA-JS 4.6.1. Startup discovers the latest stable WA-JS before checking its verified cache, with bundled fallback.
wa_js_version="bundled" skips WA-JS discovery/download; WhatsApp Web still requires a network connection. Explicit versions/URLs/files stay strict.
Preserve full message IDs, including group participant suffixes. Bare phone numbers are treated as phone numbers; explicit LIDs use @lid.
A browser profile has one owner. Close that owner before reusing it; close_already_profile=True is rejected.
Install WPP_Whatsapp[stealth] before enabling stealthy=True.
Timeouts have different units; consult configuration.

Guides and validation

Automated MCP tests use synthetic WhatsApp operations with real MCP transports. They do not certify live sending or every upstream API. Rate limiting controls local pacing; it does not guarantee account safety or platform acceptance.

Report reproducible bugs through GitHub issues. The Python project uses MIT; bundled upstream code retains its own licenses.

Metadata

Release files for WPP-Whatsapp 2.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for WPP-Whatsapp 2.2.0
File	Size	Uploaded
wpp_whatsapp-2.2.0.tar.gz	292.5 kB	Oct 13, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for WPP-Whatsapp 2.2.0
File	Interpreter	ABI	Platform	Reset
wpp_whatsapp-2.2.0-py3-none-any.whl 269.1 kB Oct 13, 2026	Python 3	none	any	Details

Total release size: 561.6 kB

Release files / wpp_whatsapp-2.2.0.tar.gz

Download URL	wpp_whatsapp-2.2.0.tar.gz
Size	292.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`bd4ab8845f888f7cb4f8c423749b8dfa901685e11849da9b4809652d0a07f378`
BLAKE2b-256 checksum How to use checksums	`e309ccf428d32f4a2ef1ccfb3df127cfb4e436c51a90ad7b31f5f59943275292`
Upload date	Oct 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.25`

Release files / wpp_whatsapp-2.2.0-py3-none-any.whl

Download URL	wpp_whatsapp-2.2.0-py3-none-any.whl
Size	269.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`27154264b1527dcbe6f2a98fe5f00aa11bc2580f67d2e0ae58d03427806f643b`
BLAKE2b-256 checksum How to use checksums	`a1235c6b492afd9986790936b6d4c6b5f9a6a9927a6b9b3367a4ee063f5a29f8`
Upload date	Oct 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.25`