WPP_Whatsapp

WPP_Whatsapp is a powerful Python library built on top of WPPConnect, bringing WhatsApp Web automation to Python developers.

💡 Looking for something else? Check out neonize - A powerful Python library built on top of Whatsmeow, enabling seamless WhatsApp automation with enterprise-grade performance.

📚 Looking for documentation? Check out our Complete Documentation

The native AsyncClient, composed services, tracked sending and release recovery are documented in the architecture and migration guide. Existing Create / Whatsapp methods remain available. See the native asyncio example.

✨ Features

Feature	Status
Automatic QR Refresh	✅
Send text, image, video, audio, documents	✅
Get contacts, chats, groups, group members	✅
Send contacts, stickers, locations	✅
Multiple Sessions Support	✅
Forward Messages	✅
Receive Messages with Callbacks	✅
Group Management	✅
Business Features	✅
Rate Limiting	✅

🚀 Quick Start

Installation

Using pip:

pip install wpp-whatsapp

Using uv (Recommended):

uv add wpp-whatsapp

Your First Bot (2 minutes)

from WPP_Whatsapp import Create

# Create and start client
creator = Create(session="mybot")

client = creator.start()
# Define message handler
def on_message(msg):
    if msg.get('body') and not msg.get('isGroupMsg'):
        # Auto-reply
        client.sendText(msg.get('from'), "Thanks for your message! 🤖")

# Register handler
client.onMessage(on_message)

print("Bot started!")

That's it! Your WhatsApp bot is now running! 🎉

JavaScript runtime and message history

The package includes WPPConnect 2.3.4 and WA-JS 4.6.1. By default, startup first checks GitHub for the latest stable WA-JS release and downloads its JavaScript asset. If the check or download fails, it uses the bundled WA-JS version. This attempt has a 30-second total timeout. To skip network access, pass Create(session="mybot", wa_js_version="bundled"). To opt into upstream nightly builds, pass Create(session="mybot", wa_js_version="nightly"). Explicit version constraints, JavaScript URLs, and local JavaScript files are also supported. Explicit selections report errors if unavailable instead of silently changing versions.

# Retrieve a page of history; opening the chat first is optional.
messages = client.getMessages("1234567890@c.us", {"count": 50})

# Retrieve all history available to this linked device.
messages = client.loadAndGetAllMessagesInChat(
    "1234567890@c.us", includeMe=True, includeNotifications=False
)

# Callbacks include the complete message ID, including group participants.
client.onMessage(lambda msg: print(msg["id"]))

Phone-to-LID mapping is resolved automatically. Pass explicit LIDs with @lid; bare phone numbers, including 14-digit numbers, are treated as phone numbers. getAllMessagesInChat returns only messages already loaded in memory.

📚 Documentation

We've created comprehensive documentation to help you:

📘 Quick Start Guide - Get started in 5 minutes
📖 API Reference - Complete method documentation
🔧 Troubleshooting - Common issues and solutions
💡 Examples - Code examples for every use case
⚡ Advanced Examples - Advanced patterns and features

Start here: Complete Documentation Index

💡 Examples

Send Messages

from WPP_Whatsapp import Create

creator = Create(session="test")
client = creator.start()
# Send text
client.sendText("1234567890@c.us", "Hello!")

# Send image
client.sendImage("1234567890@c.us", "image.jpg", "Beautiful sunset!")

# Send file
client.sendFile("1234567890@c.us", "document.pdf", "Here's the document")

# Send location
client.sendLocation("1234567890@c.us", 40.7128, -74.0060, title="New York")

Receive Messages

from WPP_Whatsapp import Create

creator = Create(session="test")
client = creator.start()

def on_message(message):
    # Ignore group messages
    if message.get('isGroupMsg'):
        return
    
    # Process message
    chat_id = message.get('from')
    text = message.get('body')
    
    if 'hello' in text.lower():
        client.sendText(chat_id, "Hi there! 👋")

client.on_message(on_message)
client.start()

Group Management

from WPP_Whatsapp import Create

creator = Create(session="test")
client = creator.start()

# Create group
group = client.createGroup("My Group", ["123@c.us", "456@c.us"])

# Add participant
client.addParticipant(group['gid'], "789@c.us")

# Send message to group
client.sendText(group['gid'], "Hello everyone!")

More Examples

📂 Basic Examples - Core functionality
⚡ Advanced Examples - Complex patterns
🗂️ Archive - Additional examples

🎯 Use Cases

WPP_Whatsapp can be used for:

🤖 Chatbots - Customer service automation
📢 Broadcasting - Safe bulk messaging with rate limiting
👥 Group Management - Automated group administration
📊 Analytics - Message tracking and statistics
🔄 Integration - Connect WhatsApp with other services
📱 Auto-replies - Intelligent response systems

⚠️ Important Notes

Rate Limiting

Always use rate limiting for bulk operations to avoid bans:

import time

contacts = ["123@c.us", "456@c.us"]
for contact in contacts:
    client.sendText(contact, "Hello")
    time.sleep(2)  # 2 second delay

Best Practices

✅ Handle errors gracefully
✅ Use unique session names
✅ Implement reconnection logic
✅ Test with small groups first
✅ Respect WhatsApp's terms of service

🆘 Need Help?

Documentation

Community

📦 Project Structure

WPP_Whatsapp/
├── WPP_Whatsapp/      # Main package
├── docs/              # Documentation
├── examples/          # Basic examples
├── scripts/           # Advanced examples
├── archive/           # Additional examples
├── tests/             # Test suite
├── README.md          # This file
├── pyproject.toml     # Project configuration
└── CHANGELOG.md       # Version history

🤝 Contributing

We welcome contributions! Here's how you can help:

📝 Improve documentation
🐛 Report bugs
💡 Suggest features
🔧 Submit pull requests
📚 Add examples

See Contributing Guide for details.

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

Built on top of WPPConnect
Powered by Playwright

Made with ❤️ by Ammar Alkotb

Happy Coding! 🎉

Metadata

Release files for WPP-Whatsapp 2.0.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.0.0
File	Size	Uploaded
wpp_whatsapp-2.0.0.tar.gz	265.9 kB	Oct 13, 2026	Details

Built distribution (wheel)

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

Total release size: 514.0 kB

Release files / wpp_whatsapp-2.0.0.tar.gz

Download URL	wpp_whatsapp-2.0.0.tar.gz
Size	265.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`a4d38019db05de69a697661dfbbf2777015018ad416b459e84b93b66ad431e4d`
BLAKE2b-256 checksum How to use checksums	`74593303ab4cad5c5aaa5e4989b425fad996bb76acdd285bdd764e8dd2526291`
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.0.0-py3-none-any.whl

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