waha 1.0.0

Python package for WAHA (WhatsApp HTTP API)

WAHA - Python

A comprehensive Python package for the WAHA (WhatsApp HTTP API) service. This package provides a clean, type-safe, and easy-to-use interface for interacting with WhatsApp through the WAHA API.

🌟 Features

• 🔄 Full API Coverage: Complete implementation of all WAHA API endpoints
• ⚡ Async & Sync Support: Both synchronous and asynchronous operation modes
• 🛡️ Type Safety: Full typing with Pydantic models for request/response validation
• 🎯 Organized Namespaces: Intuitive organization by functionality (auth, sessions, messages, etc.)
• 📝 Rich Documentation: Comprehensive docstrings and examples
• 🧪 Well Tested: Extensive test coverage with pytest
• 🐍 Modern Python: Support for Python 3.8+ with modern async/await patterns

🚀 Quick Start

Installation

pip install waha

Basic Usage

from waha import WahaClient

# Initialize the client
client = WahaClient(
    base_url="http://localhost:3000",
    api_key="your-api-key"  # Optional, can use WAHA_API_KEY env var
)

# Start a session
session = client.sessions.start("default")

# Send a text message
message = client.messages.send_text(
    session="default",
    chat_id="[e-mail]",
    text="Hello from WAHA! 👋"
)

print(f"Message sent: {message.id}")

Async Usage

import asyncio
from waha import AsyncWahaClient

async def main():
    async with AsyncWahaClient(
        base_url="http://localhost:3000",
        api_key="your-api-key"
    ) as client:
        # Start a session
        session = await client.sessions.start("default")
        
        # Send a message
        message = await client.messages.send_text(
            session="default",
            chat_id="[e-mail]",
            text="Hello from async WAHA! 🚀"
        )
        
        print(f"Message sent: {message.id}")

asyncio.run(main())

📚 Documentation

Core Components

The SDK is organized into several namespaces, each handling a specific area of functionality:

🔑 Authentication (client.auth)

Handle QR code authentication and phone verification:

# Get QR code for authentication
qr_code = client.auth.get_qr_code("default", format="raw")
print(f"QR Code: {qr_code.qr}")

# Request authentication code
client.auth.request_code("default", phone_number="[phone]")

🖥️ Sessions (client.sessions)

Manage WhatsApp sessions:

# Create and start a session
session = client.sessions.create("my-session", start=True)

# List all sessions
sessions = client.sessions.list()

# Get session info
info = client.sessions.get("default")

# Stop a session
client.sessions.stop("default")

# Get authenticated account info
me = client.sessions.get_me("default")
print(f"Logged in as: {me.pushName} ({me.id})")

📤 Messages (client.messages)

Send various types of messages:

# Send text message
client.messages.send_text(
    chat_id="[e-mail]",
    text="Hello! 👋",
    reply_to="message_id_to_reply_to"  # Optional
)

# Send image
client.messages.send_image(
    chat_id="[e-mail]",
    file="https://example.com/image.jpg",
    caption="Check this out!"
)

# Send document
client.messages.send_file(
    chat_id="[e-mail]",
    file="https://example.com/document.pdf",
    caption="Important document"
)

# Send location
client.messages.send_location(
    chat_id="[e-mail]",
    latitude=40.7128,
    longitude=-74.0060,
    title="New York City"
)

# Send contact
from waha.types import ContactVcard

contact = ContactVcard(
    fullName="John Doe",
    phoneNumber="[phone]",
    email="[e-mail]"
)
client.messages.send_contact_vcard(
    chat_id="[e-mail]",
    contacts=[contact]
)

# Send poll
client.messages.send_poll(
    chat_id="[e-mail]",
    poll_text="What's your favorite color?",
    options=["Red", "Green", "Blue", "Yellow"]
)

# Send buttons
buttons = [
    {"id": "btn1", "title": "Option 1"},
    {"id": "btn2", "title": "Option 2"},
]
client.messages.send_buttons(
    chat_id="[e-mail]",
    text="Choose an option:",
    buttons=buttons
)

# React to a message
client.messages.react(
    message_id="some_message_id",
    reaction="👍"
)

# Forward a message
client.messages.forward_message(
    message_id="source_message_id",
    chat_id="target_chat_id"
)

💬 Chats (client.chats)

Manage chats and retrieve messages:

# List chats
chats = client.chats.list(limit=50)

# Get messages from a chat
messages = client.chats.get_messages(
    chat_id="[e-mail]",
    limit=100
)

👤 Contacts (client.contacts)

Manage contacts:

# Check if a number exists on WhatsApp
result = client.contacts.check_exists("[phone]")
if result.numberExists:
    print(f"Number exists! Chat ID: {result.chatId}")

🆔 Profile (client.profile)

Manage your WhatsApp profile:

# Get profile info
profile = client.profile.get()
print(f"Name: {profile.name}, Status: {profile.status}")

# Update profile name
client.profile.set_name("New Name")

# Update profile status
client.profile.set_status("Available")

# Set profile picture
client.profile.set_picture("https://example.com/avatar.jpg")

👥 Groups (client.groups)

Manage WhatsApp groups:

# Create a group
group = client.groups.create(
    name="My Group",
    participants=["[e-mail]", "[e-mail]"]
)

# Add participants
client.groups.add_participants(
    group_id="[e-mail]",
    participants=["[e-mail]"]
)

🔧 Configuration

Environment Variables

You can configure the SDK using environment variables:

export WAHA_URL="http://localhost:3000"
export WAHA_API_KEY="your-api-key"

Client Configuration

client = WahaClient(
    base_url="http://localhost:3000",
    api_key="your-api-key",
    timeout=30.0,  # Request timeout in seconds
    headers={"Custom-Header": "value"}  # Additional headers
)

📁 File Handling

The SDK supports multiple ways to handle files:

Using URLs

client.messages.send_image(
    chat_id="[e-mail]",
    file="https://example.com/image.jpg"
)

Using Base64

from waha.types import Base64File

file = Base64File(
    mimetype="image/jpeg",
    filename="image.jpg",
    data="base64_encoded_data_here"
)

client.messages.send_image(
    chat_id="[e-mail]",
    file=file
)

Using URLFile Objects

from waha.types import URLFile

file = URLFile(
    url="https://example.com/image.jpg",
    filename="custom_name.jpg"
)

client.messages.send_image(
    chat_id="[e-mail]",
    file=file
)

🚨 Error Handling

The SDK provides specific exception types for different error scenarios:

from waha.exceptions import (
    WahaException,
    WahaAPIError,
    WahaTimeoutError,
    WahaAuthenticationError,
    WahaSessionError
)

try:
    message = client.messages.send_text(
        chat_id="invalid_chat_id",
        text="Hello"
    )
except WahaAuthenticationError:
    print("Authentication failed - check your API key")
except WahaAPIError as e:
    print(f"API error: {e.message} (Status: {e.status_code})")
except WahaTimeoutError:
    print("Request timed out")
except WahaException as e:
    print(f"General WAHA error: {e}")

🧪 Testing

Run the test suite:

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=waha_sdk

# Run specific test file
pytest tests/test_client.py

🔄 Development

Setting up for development:

# Clone the repository
git clone https://github.com/devlikeapro/waha-python.git
cd waha-python

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

# Format code
black waha tests examples

# Type checking
mypy waha

Project Structure

waha-python/
├── waha/
│   ├── __init__.py
│   ├── client.py              # Main client classes
│   ├── exceptions.py          # Custom exceptions
│   ├── types.py              # Pydantic models
│   ├── http_client.py        # HTTP client implementation
│   └── namespaces/           # API namespaces
│       ├── auth.py
│       ├── sessions.py
│       ├── messages.py
│       └── ...
├── tests/                    # Test suite
├── examples/                 # Usage examples
├── pyproject.toml           # Package configuration
└── README.md

📋 Requirements

• Python 3.8+
• httpx >= 0.24.0
• pydantic >= 2.0.0

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for your changes
5. Ensure all tests pass (pytest)
6. Commit your changes (git commit -m 'Add some amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• WAHA Documentation: https://waha.devlike.pro
• WAHA GitHub: https://github.com/devlikeapro/waha
• PyPI Package: https://pypi.org/project/waha/
• Issues: https://github.com/devlikeapro/waha-python/issues

🆘 Support

If you encounter any issues or have questions:

1. Check the documentation
2. Search existing issues
3. Create a new issue with detailed information about your problem

🎯 Roadmap

• Add webhook handling utilities
• Implement retry logic with exponential backoff
• Add rate limiting support
• Create CLI tool for common operations
• Add more comprehensive examples
• Support for WhatsApp Business API features

🙏 Acknowledgments

• Thanks to the WAHA project for providing the WhatsApp HTTP API
• Built with httpx for HTTP client functionality
• Uses Pydantic for data validation and serialization