██████╗ █████╗ ██╗██╗ ███████╗██╗ ██╗███████╗ ██████╗ ██╗ ██╗ ██╔══██╗██╔══██╗██║██║ ██╔════╝╚██╗ ██╔╝██╔════╝ ██╔══██╗╚██╗ ██╔╝ ██████╔╝███████║██║██║ █████╗ ╚████╔╝ ███████╗█████╗██████╔╝ ╚████╔╝ ██╔══██╗██╔══██║██║██║ ██╔══╝ ╚██╔╝ ╚════██║╚════╝██╔═══╝ ╚██╔╝ ██████╔╝██║ ██║██║███████╗███████╗ ██║ ███████║ ██║ ██║ ╚═════╝ ╚═╝ ╚═╝╚═╝╚══════╝╚══════╝ ╚═╝ ╚══════╝ ╚═╝ ╚═╝
Async Python package for WhatsApp Web protocol surfaces, inspired by Node Baileys.
Install · Quickstart · API Examples · Feature Status · Contributing
Alpha release: start with a dedicated test account and review the feature status before using this package in a production service.
python -m pip install baileys-pythonfrom baileys import WhatsAppClient, make_socket| Area | Capabilities |
|---|---|
| Auth and sockets | QR pairing, saved auth reconnect, keepalive, logout, disconnect reasons, async event emitter |
| Messaging | send/receive text, common message builders, replies, mentions, reactions, edits, deletes, retry replay |
| Media | image, video, audio, document, and sticker send/download/decrypt helpers |
| Events and store | message, receipt, chat, contact, group, presence, call, notification, dirty, and offline events |
| Account APIs | chat, profile, privacy, presence, blocklist, and group method surfaces |
| Persistence | in-memory, SQLite, and Postgres auth/event/replay store surfaces |
| Protocol foundation | generated WAProto, WABinary tokens, Noise, Signal wrappers, crypto, media/app-state keys |
| Migration | Pythonic async methods plus common Baileys-compatible aliases |
Some WhatsApp features are account-gated or rollout-dependent. Unsupported or rejected server behavior is surfaced through typed errors instead of being silently hidden.
Python app
|
v
WhatsAppClient / make_socket
|
+-- AuthState and Signal keys
+-- EventEmitter and optional store
+-- WABinary, WAProto, Noise, Signal, media crypto
|
v
WhatsApp Web socket
import asyncio
from pathlib import Path
from baileys import WhatsAppWebClient
async def main() -> None:
async with WhatsAppWebClient(Path("auth/live_pair_creds.json")) as client:
success = await client.wait_for_success(timeout=60)
print(success.attrs)
asyncio.run(main())import asyncio
from baileys import make_socket
async def main() -> None:
client = make_socket("auth/product_qr_creds.json")
try:
await client.connect_and_wait(start_receive_loop=True)
result = await client.send_message(
"15551234567@s.whatsapp.net",
{"text": "hello from Python"},
)
print(result.message_id, result.status)
finally:
await client.close()
asyncio.run(main())| Link | Description |
|---|---|
| Docs site | Hosted documentation |
| Quickstart | Install, connect, send, and receive |
| API examples | Auth, messages, media, groups, stores |
| Public API | Current exported API surface |
| Feature status | Working, alpha, and deferred areas |
| Migration guide | Notes for Node Baileys users |
| Contributing | Local setup, checks, PR guidance |
| Changelog | Release notes |
python -m pip install -e ".[dev]"
python -m pytest -qBuild the documentation site locally:
python -m pip install -e ".[docs]"
python -m mkdocs serveRun the full release gate:
python scripts/release_gate.pyThis project is unofficial. It is not affiliated with, endorsed by, sponsored by, or maintained by WhiskeySockets/Baileys, WhatsApp, Meta, or any of their subsidiaries or affiliates. WhatsApp and related names, marks, emblems, and images are trademarks of their respective owners.
Use the package responsibly:
- use a dedicated test account first
- keep saved auth state and Signal keys private
- respect recipient consent and opt-out requests
- do not use it for spam or platform enforcement evasion
This package is released under the MIT License. See LICENSE and NOTICE for license text, attribution, and affiliation notices.