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

---

✨ 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.on_message(on_message)

# Start bot
print("Bot started! Scan QR code...")
client.start()

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

---

📚 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

• 📚 Complete Documentation
• 🚀 Quick Start Guide
• 🔧 Troubleshooting

Community

• 💬 GitHub Discussions
• 🐛 Report Issues
• 💡 Feature Requests

---

📦 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! 🎉