waha-python 1.0.0

Unofficial WhatsApp HTTP API (WAHA) Python Client - Complete implementation of WAHA API

WAHA Python

Unofficial Python client library for WAHA (WhatsApp HTTP API) - a powerful solution to interact with WhatsApp Web through HTTP API.

Features

✅ Complete API Coverage - Support for all WAHA endpoints

• 📤 Send Messages: Text, Image, Video, Voice, File, Location, Contact, Poll
• 📥 Receive Messages: Webhooks and Event Handling
• 💬 Chats Management: List, Archive, Read, Delete
• 👤 Contacts Management: Get, Update, Block, Check Existence
• 👥 Groups Management: Create, Manage, Admin Controls
• 🟢 Status Management: Send and Manage WhatsApp Status
• 📢 Channels Management: Create and Manage Channels
• 🔐 Session Management: Create, Start, Stop, QR Code
• And much more!

✅ Simple & Intuitive - Clean, Pythonic API design ✅ Type Hints - Full type hints for better IDE support ✅ Error Handling - Comprehensive error handling ✅ Documentation - Complete documentation and examples

Installation

pip install waha-python

Or install from source:

git clone https://github.com/teguh02/waha-python.git
cd waha-python
pip install -e .

Quick Start

1. Start WAHA Server

First, you need to have WAHA server running. Follow the Quick Start Guide:

docker pull devlikeapro/waha
docker run -it --env-file .env -v "$(pwd)/sessions:/app/.sessions" --rm -p 3000:3000 --name waha devlikeapro/waha

2. Use the Python Client

from waha_python import WAHAClient

# Initialize the client
client = WAHAClient(
    base_url="http://localhost:3000",
    api_key="your-api-key-here"  # Optional, if you set WAHA_API_KEY
)

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

print(f"Message sent: {result}")

3. Create Session with QR Code

# Create a new session
session = client.sessions.create(
    name="my_session",
    config={
        "webhooks": [{
            "url": "https://your-webhook-url.com/webhook",
            "events": ["message"]
        }]
    }
)

# Get QR code for authentication
qr_code = client.sessions.get_qr("my_session", accept_json=True)
print(f"QR Code (Base64): {qr_code['data']}")

# Scan the QR code with your WhatsApp app
# The session status will change to WORKING

4. Receive Messages with Webhooks

from flask import Flask, request

app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
def webhook():
    data = request.get_json()
    
    if data.get("event") == "message":
        payload = data["payload"]
        from_number = payload["from"]
        message_text = payload.get("body", "")
        
        print(f"Received: {message_text} from {from_number}")
        
        # Reply to the message
        client.messages.send_text(
            session=data["session"],
            chat_id=from_number,
            text=f"You said: {message_text}"
        )
    
    return "OK"

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)

Complete Examples

Send Different Types of Messages

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

# Send image with URL
client.messages.send_image(
    session="default",
    chat_id="[e-mail]",
    file={"url": "https://example.com/image.jpg", "mimetype": "image/jpeg"},
    caption="Check this out!"
)

# Send image from file
client.messages.send_image(
    session="default",
    chat_id="[e-mail]",
    file="path/to/image.jpg",
    caption="My image"
)

# Send video
client.messages.send_video(
    session="default",
    chat_id="[e-mail]",
    file={"url": "https://example.com/video.mp4", "mimetype": "video/mp4"}
)

# Send voice message
client.messages.send_voice(
    session="default",
    chat_id="[e-mail]",
    file={"url": "https://example.com/voice.opus", "mimetype": "audio/ogg; codecs=opus"}
)

# Send document
client.messages.send_file(
    session="default",
    chat_id="[e-mail]",
    file={"url": "https://example.com/document.pdf", "mimetype": "application/pdf"}
)

# Send location
client.messages.send_location(
    session="default",
    chat_id="[e-mail]",
    latitude=38.8937255,
    longitude=-77.0969763,
    title="My Location"
)

# Send contact
client.messages.send_contact(
    session="default",
    chat_id="[e-mail]",
    contacts=[{
        "fullName": "John Doe",
        "organization": "Company",
        "phoneNumber": "[phone]",
        "whatsappId": "911111111111"
    }]
)

# Send poll
client.messages.send_poll(
    session="default",
    chat_id="[e-mail]",
    poll={
        "name": "How are you?",
        "options": ["Awesome!", "Good!", "Not bad!"],
        "multipleAnswers": False
    }
)

Manage Sessions

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

# List all sessions including stopped ones
all_sessions = client.sessions.list(all_sessions=True)

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

# Create session
new_session = client.sessions.create(
    name="my_session",
    config={"webhooks": [...]}
)

# Start session
client.sessions.start("my_session")

# Stop session
client.sessions.stop("my_session")

# Restart session
client.sessions.restart("my_session")

# Logout session
client.sessions.logout("my_session")

# Delete session
client.sessions.delete("my_session")

# Get QR code
qr = client.sessions.get_qr("default", accept_json=True)

# Request pairing code
code_info = client.sessions.request_code("default", "12132132130")
print(f"Pairing code: {code_info['code']}")

Manage Chats

# List all chats
chats = client.chats.list("default")

# Get chat picture
picture = client.chats.get_picture("default", "[e-mail]")

# Archive chat
client.chats.archive("default", "[e-mail]")

# Unarchive chat
client.chats.unarchive("default", "[e-mail]")

# Mark as unread
client.chats.unread("default", "[e-mail]")

# Read messages
client.chats.read_messages("default", "[e-mail]")

# Get messages
messages = client.chats.get_messages("default", "[e-mail]", limit=100)

# Get specific message
message = client.chats.get_message(
    "default",
    "[e-mail]",
    "message_id_here"
)

# Delete chat
client.chats.delete("default", "[e-mail]")

Manage Contacts

# List all contacts
contacts = client.contacts.list_all("default")

# Get specific contact
contact = client.contacts.get_contact("default", "1234567890")

# Update contact
client.contacts.update(
    "default",
    "[e-mail]",
    first_name="John",
    last_name="Doe"
)

# Check if phone exists
result = client.contacts.check_exists("default", "1234567890")
if result["numberExists"]:
    print(f"Chat ID: {result['chatId']}")

# Get contact about
about = client.contacts.get_about("default", "1234567890")

# Get profile picture
profile_pic = client.contacts.get_profile_picture("default", "1234567890")

# Block contact
client.contacts.block("default", "[e-mail]")

# Unblock contact
client.contacts.unblock("default", "[e-mail]")

Manage Groups

# List all groups
groups = client.groups.list("default")

# Get specific group
group = client.groups.get("default", "[e-mail]")

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

# Update group name
client.groups.update_subject("default", "[e-mail]", "Updated Name")

# Update group description
client.groups.update_description("default", "[e-mail]", "Description")

# Get invite code
invite_code = client.groups.get_invite_code("default", "[e-mail]")

# Revoke invite code
client.groups.revoke_invite_code("default", "[e-mail]")

# Get participants
participants = client.groups.get_participants("default", "[e-mail]")

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

# Remove participants
client.groups.remove_participants(
    "default",
    "[e-mail]",
    ["[e-mail]"]
)

# Promote to admin
client.groups.promote_admin(
    "default",
    "[e-mail]",
    ["[e-mail]"]
)

# Demote from admin
client.groups.demote_admin(
    "default",
    "[e-mail]",
    ["[e-mail]"]
)

# Leave group
client.groups.leave("default", "[e-mail]")

Manage Status (Stories)

# Send text status
client.status.send_text("default", "My status update")

# Send image status
client.status.send_image(
    "default",
    file={"url": "https://example.com/image.jpg", "mimetype": "image/jpeg"}
)

# Send video status
client.status.send_video(
    "default",
    file={"url": "https://example.com/video.mp4", "mimetype": "video/mp4"}
)

# Send voice status
client.status.send_voice(
    "default",
    file={"url": "https://example.com/voice.opus", "mimetype": "audio/ogg; codecs=opus"}
)

# Delete status
client.status.delete("default", "message_id_here")

# Get new message ID
message_id = client.status.get_new_message_id("default")

Manage Channels

# List all channels
channels = client.channels.list("default")

# Get specific channel
channel = client.channels.get("default", "channel_id")

# Create channel
new_channel = client.channels.create("default", "My Channel", "Description")

# Get channel messages
messages = client.channels.get_messages("default", "channel_id", limit=100)

# Delete channel
client.channels.delete("default", "channel_id")

Message Reactions and Actions

# Add reaction
client.messages.add_reaction(
    session="default",
    message_id="message_id_here",
    reaction="👍"
)

# Remove reaction
client.messages.add_reaction(
    session="default",
    message_id="message_id_here",
    reaction=""
)

# Star message
client.messages.star_message(
    session="default",
    chat_id="[e-mail]",
    message_id="message_id_here"
)

# Unstar message
client.messages.star_message(
    session="default",
    chat_id="[e-mail]",
    message_id="message_id_here",
    star=False
)

# Edit message
client.messages.edit_message(
    session="default",
    chat_id="[e-mail]",
    message_id="message_id_here",
    text="Updated message"
)

# Delete message
client.messages.delete_message(
    session="default",
    chat_id="[e-mail]",
    message_id="message_id_here"
)

# Forward message
client.messages.forward_message(
    session="default",
    chat_id="[e-mail]",
    message_id="message_id_here"
)

# Pin message
client.messages.pin_message(
    session="default",
    chat_id="[e-mail]",
    message_id="message_id_here"
)

# Unpin message
client.messages.unpin_message(
    session="default",
    chat_id="[e-mail]",
    message_id="message_id_here"
)

Error Handling

from waha_python import WAHAClient, WAHAAuthenticationError, WAHANotFoundError

try:
    client = WAHAClient(base_url="http://localhost:3000", api_key="wrong-key")
    result = client.messages.send_text(
        session="default",
        chat_id="[e-mail]",
        text="Hello"
    )
except WAHAAuthenticationError:
    print("Authentication failed")
except WAHANotFoundError:
    print("Resource not found")
except Exception as e:
    print(f"Error: {e}")

Using Context Manager

from waha_python import WAHAClient

with WAHAClient(base_url="http://localhost:3000", api_key="your-key") as client:
    result = client.messages.send_text(
        session="default",
        chat_id="[e-mail]",
        text="Hello from context manager!"
    )
# Client is automatically closed

Requirements

• Python 3.8+
• requests library
• WAHA server running (see Quick Start Guide)

Documentation

• WAHA Documentation
• WAHA GitHub

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Support

• GitHub Issues: https://github.com/teguh02/waha-python/issues
• WAHA Documentation: https://waha.devlike.pro

Important Disclaimer

This is an UNOFFICIAL community project and is not affiliated, associated, authorized, endorsed by, or in any way officially connected with:

• WhatsApp LLC or any of its subsidiaries or affiliates
• WAHA (devlikeapro) team

The official WhatsApp website can be found at whatsapp.com.
The official WAHA documentation can be found at waha.devlike.pro.

"WhatsApp" as well as related names, marks, emblems and images are registered trademarks of their respective owners.

Usage Warning

This library interacts with WhatsApp through unofficial means. There are risks associated with using unofficial WhatsApp clients:

• Account suspension or banning
• Security risks
• Data privacy concerns
• No official support

Use at your own risk. For business applications, we recommend using the official WhatsApp Business API.