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.
The 12 tools cover session control, paginated chat/history reads, complete
message-ID lookup, contacts, group members, tracked text sending and receipt
inspection/reconciliation. --read-only omits send/reconciliation tools.
One server owns one account shared by its MCP clients. See
FastMCP configuration and delivery semantics.
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=Trueis rejected. - Install
WPP_Whatsapp[stealth]before enablingstealthy=True. - Timeouts have different units; consult configuration.
Guides and validation
- Quick start, API reference, generated service signatures
- Troubleshooting, FAQ, usage practices, performance
- Runnable examples, application templates
- Development, tests and validation boundaries, changelog
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.
1 maintainer
Metadata
1 maintainer
Release files for WPP-Whatsapp 2.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| wpp_whatsapp-2.1.0.tar.gz | 273.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| wpp_whatsapp-2.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 527.2 kB
Release files / wpp_whatsapp-2.1.0.tar.gz
| Download URL | wpp_whatsapp-2.1.0.tar.gz |
|---|---|
| Size | 273.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ae76463e6520392e4f8582bac694aa28b4c36ac6ab7c891a7c046389c561dbd8
|
|
BLAKE2b-256 checksum How to use checksums |
54dfd12027cd2dfb040b85576b882e5ac98e7151f9d3f86f9a98c74561786ab4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Release files / wpp_whatsapp-2.1.0-py3-none-any.whl
| Download URL | wpp_whatsapp-2.1.0-py3-none-any.whl |
|---|---|
| Size | 254.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ab56bb1ff876f77b4ab4ca84c494758c95ca76c21844bb5eb453f07d2d96a07c
|
|
BLAKE2b-256 checksum How to use checksums |
b06ee9061c1bc437b5de9e7240782a05f6eb1cd457b8ce7c0401cb276d478953
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
