WPP_Whatsapp
Automate WhatsApp Web from Python.
Build message listeners, read conversations, work with media, and connect WhatsApp
to MCP clients. WPP_Whatsapp brings together
WPPConnect,
WA-JS, and Playwright, with both
synchronous and native asyncio interfaces.
Documentation · PyPI · Releases · Report an issue
On this page
- What you can build
- Installation
- Quick start
- Native asyncio
- MCP integration
- Sessions and delivery
- Documentation
- Contributing and support
- License
What you can build
- Message workflows: receive incoming messages, read chat history, send text, and reply to conversations.
- Media integrations: send images and documents, and download message media.
- Contact and group tools: look up contacts, list chats, and read group members.
- Async applications: use native
asyncioservices for messages, chats, events, and more, with optional typed read results. - MCP integrations: expose WhatsApp tools over stdio or local HTTP, with account isolation, access policies, diagnostics, and tracked sends.
Installation
You need Python 3.9+, Chrome or Playwright Chromium, and an internet connection. The optional MCP integration requires Python 3.10+.
Install the Python library:
python -m pip install --upgrade WPP_Whatsapp
For MCP support, install the optional extra instead:
python -m pip install --upgrade "WPP_Whatsapp[mcp]"
Chrome is the default browser. You can also use Playwright Chromium; see the
installation guide
for browser setup, optional FFmpeg support, and the stealth extra.
Quick start: receive messages
Save this as listener.py, then run python listener.py:
from threading import Event
from WPP_Whatsapp import Create
def incoming(message):
print("Received message ID:", message.get("id"))
with Create(session="mybot", autoClose=0) as client:
client.onMessage(incoming)
print("Listening; press Ctrl+C to close.")
Event().wait()
On the first run, scan the QR code in the browser with WhatsApp on your phone.
Use the same session name on later runs to reuse the saved login.
The example prints incoming message IDs and keeps listening until you press Ctrl+C.
Leaving the with block closes the client's resources while preserving the login.
Create manages startup and returns the ready client when you enter the with
block. If you manage startup yourself, use creator.start() to get that client
before registering callbacks or calling methods.
Use native asyncio
Choose AsyncClient for an application that already uses asyncio.
This example loads up to ten chats:
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())
Keep each async client on the event loop that created it. Native services use
snake_case method names; existing flat methods keep their names and raw results.
See the API reference
for sending, history, and media examples, or the
migration guide
for moving existing code to native services.
Connect an MCP client
With the mcp extra installed, configure your MCP client to launch:
wpp-whatsapp-mcp --session mybot
This uses stdio. To run a local HTTP server instead:
wpp-whatsapp-mcp --session mybot --transport http --port 8765
The HTTP endpoint is http://127.0.0.1:8765/mcp.
Once the server is running:
- Call
whatsapp_connectfrom your MCP client. - Complete WhatsApp login in the browser.
- Poll
whatsapp_statusuntilreadyis true.
Starting the MCP server alone does not open WhatsApp. Version 2.3.0 provides
23 tools for sessions, chats, messages, search, events, media, diagnostics and ACK evidence.
Use --read-only to omit sending and reconciliation tools, leaving 18 tools.
The FastMCP guide covers client configuration, multiple accounts, verified JWT access policies, and delivery tracking. MCP was introduced in 2.1.0 with 12 tools; the expanded toolset requires 2.2.0 or newer.
Version 2.3.0 adds request-bound operation IDs, optional durable event journals, bounded connection recovery, delivery/read ACK waits, and admission/rate controls. See the reliability and migration guide, release status, and runnable HTTP/MCP examples.
Working with sessions and delivery
- Reuse sessions consistently. Each browser profile has one owner at a time.
Close the current owner before reusing it;
close_already_profile=Trueis rejected. - Keep complete IDs. Preserve message IDs exactly, including group participant
suffixes. Bare phone numbers are treated as phone numbers; explicit LIDs use
@lid. - Check send receipts before retrying. Tracked service sends return receipts. A confirmed message ID does not prove recipient delivery or reading. See delivery semantics before adding automatic retries.
- Choose the runtime when needed. Startup normally discovers the latest stable
WA-JS, checks its verified cache, and falls back to bundled assets. Set
wa_js_version="bundled"to skip discovery and download. WhatsApp Web still needs an internet connection. Explicit versions, URLs, and files are strict selections. - Check optional settings.
stealthy=TruerequiresWPP_Whatsapp[stealth]. Timeout units vary by setting; see configuration.
Bundled assets: WPPConnect 2.3.4 and WA-JS 4.6.1.
Explore the documentation
| I want to… | Start here |
|---|---|
| Set up the library and browser | Installation |
| Open a session and read messages | Quick start |
| Find methods and arguments | API reference · Service signatures |
| Configure profiles and timeouts | Configuration |
| Use typed reads and bounded media operations | Typed reads and media |
| Run a complete example | Examples · Application templates |
| Resolve a problem | Troubleshooting · FAQ |
| Plan reliable application behavior | Usage practices · Performance |
Contributing and support
For bugs, open a GitHub issue with a minimal example and sanitized version and error details. For code contributions, start with the development guide and test guide. Release changes are recorded in the changelog.
Automated MCP tests use synthetic WhatsApp operations with real MCP transports; they do not certify live sending or every upstream API. Local rate limiting controls pacing and does not guarantee platform acceptance or account safety.
License
The Python project is licensed under MIT. Bundled JavaScript dependencies retain their upstream licenses.
1 maintainer
Metadata
1 maintainer
Release files for WPP-Whatsapp 2.3.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.3.0.tar.gz | 307.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| wpp_whatsapp-2.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 588.4 kB
Release files / wpp_whatsapp-2.3.0.tar.gz
| Download URL | wpp_whatsapp-2.3.0.tar.gz |
|---|---|
| Size | 307.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7531138e3e54416585aacd970d49548e6202d1571d57aa7cb037e09432342b66
|
|
BLAKE2b-256 checksum How to use checksums |
0dfd4ea14c84f10a6aed2b5985e1c598ea323dddc0a053add61dbde1688207cf
|
| 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.3.0-py3-none-any.whl
| Download URL | wpp_whatsapp-2.3.0-py3-none-any.whl |
|---|---|
| Size | 280.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5bf29f9122b4ba4657bdb0751f30627c7746732043ab805e3586d729e8d8f7ff
|
|
BLAKE2b-256 checksum How to use checksums |
944f85a24bf49a69d87a490561cdeb257bc6e128632391da98d2f041a7844e2b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
