waton 0.1.0

Python WhatsApp Web Multi-Device library

Waton

Waton is a lightweight, standalone Python library for WhatsApp Web Multi-Device. Build WhatsApp bots, automation tools, and messaging applications entirely in Python — no Node.js required.

Why Waton?

• Pure Python — Native async/await API, integrates seamlessly with your Python stack
• Blazing Fast Crypto — Signal Protocol encryption powered by Rust (via PyO3)
• Lightweight — ~30-60MB memory footprint, minimal dependencies
• Multi-Device Ready — Full support for WhatsApp's multi-device architecture
• No Node.js — Not a Baileys wrapper, zero JavaScript runtime dependency

Features

• QR Code & Phone Number Pairing
• Send & Receive Text Messages
• Multi-Device Message Routing
• End-to-End Encryption (Signal Protocol)
• Persistent Session Storage (SQLite)
• Async/Await Native API

Installation

pip install waton

Prebuilt wheels include the Rust crypto extension — no Rust toolchain needed for installation.

For development:

pip install -e .[dev]
maturin develop

How To Use

Waton provides both a high-level App interface (recommended) and a low-level WAClient interface.

1. Interactive CLI Chat (Easiest Way to Test)

We provide a built-in interactive terminal chat. If you just want to test sending and receiving messages via your terminal, run:

python examples/cli_chat.py

• When you run this for the first time, it will print a QR code in the terminal. Scan it with your WhatsApp app (Linked Devices).
• Once connected, any incoming messages to your number will be printed live in the terminal.
• To send a message, simply type NOMOR_TUJUAN pesan yang ingin dikirim (e.g., 628123456789 Halo dari terminal!) and press Enter.

2. High-Level API (App)

For building bots or automated tools, use the App class. It manages the connection, storage, and message parsing automatically, providing a simple decorator-based router.

import asyncio
from waton.app.app import App
from waton.app.context import Context

# 1. Initialize App (creates SQLite session DB)
app = App(storage_path="my_session.db")

# 2. Listen for incoming messages
@app.message()
async def on_message(ctx: Context):
    msg = ctx.message
    print(f"Message received from {msg.from_jid}: {msg.text}")
    
    # Auto-reply if there is text
    if msg.text:
        reply_text = f"Hello! You said: {msg.text}"
        await ctx.app.messages.send_text(to_jid=msg.from_jid, text=reply_text)

# 3. Connection ready callback
@app.on_ready
async def on_ready(app_instance: App):
    print("Bot is connected and ready to receive messages!")

# 4. Run the loop
if __name__ == "__main__":
    app.run()

3. Low-Level API (WAClient)

If you want direct control over the WebSocket or need to build custom wrappers, you can use the WAClient directly. See examples/live_connect.py for a full example.

Architecture

┌─────────────────────────────────────────────────┐
│                   Your App                       │
├─────────────────────────────────────────────────┤
│  MessagesAPI  │  ChatsAPI  │  GroupsAPI  │ ...  │
├─────────────────────────────────────────────────┤
│                   WAClient                       │
│         (WebSocket + Noise Protocol)             │
├─────────────────────────────────────────────────┤
│              Signal Protocol (E2EE)              │
│           ┌─────────────────────┐                │
│           │   Rust Crypto Core  │                │
│           │  (Curve25519, AES)  │                │
│           └─────────────────────┘                │
├─────────────────────────────────────────────────┤
│           SQLiteStorage (Sessions)               │
└─────────────────────────────────────────────────┘

Waton vs Baileys

Aspect	Waton (Python)	Baileys (Node.js)
Runtime	Python (~30-50MB)	Node.js (~50-100MB)
Package Size	~500KB + deps	~2MB + node_modules
Crypto Engine	Rust native (PyO3)	JS/WASM
Memory Usage	~30-60MB	~80-150MB
Startup Time	Faster	Slower (JIT)
Encryption Speed	Faster (native)	Slower (WASM)
Maturity	New	Mature
Community	Growing	Large

Choose Waton when:

• Building Python-native applications
• Running on resource-constrained environments (VPS, Raspberry Pi, Docker)
• Need minimal memory footprint
• Want native async/await integration with FastAPI, Django, etc.

Choose Baileys when:

• Already invested in Node.js ecosystem
• Need battle-tested stability for production
• Require extensive community support and plugins

Requirements

• Python 3.10+
• WhatsApp account (phone number)
• Internet connection

Contributing

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

# Setup development environment
git clone https://github.com/kaivyy/waton.git
cd waton
pip install -e .[dev]
maturin develop

# Run tests
pytest tests/

License

MIT License — feel free to use in personal and commercial projects.

Disclaimer

This project is not affiliated with WhatsApp or Meta. Use responsibly and in accordance with WhatsApp's Terms of Service.