Getting Started

Getting Started#

Requirements#

  • Python 3.11+

  • A WhatsApp account on a phone

  • Internet connectivity

Install#

pip install waton

For local development:

pip install -e .[dev]
maturin develop

Fastest bot start (simple callback API)#

For the most minimal import-first workflow:

from waton import simple

client = simple(storage_path="my_session.db")

@client.on_message
async def on_message(msg):
    if msg.text:
        await msg.reply(f"Echo: {msg.text}")

@client.on_ready
async def on_ready(bot):
    print("ready")

if __name__ == "__main__":
    client.run()

msg exposes ergonomic fields/methods:

  • msg.id

  • msg.text

  • msg.from_jid

  • msg.sender

  • await msg.reply(text)

  • await msg.react(emoji)

First connection test#

Run the live connectivity example:

python -u examples/live_connect.py

Expected flow:

  1. QR is printed in terminal.

  2. Scan from WhatsApp Linked Devices.

  3. After pairing and reconnect, status becomes open.

  4. Ping IQ receives type=result.

Optional message send test#

PowerShell:

$env:WATON_AUTH_DB='waton_live.db'
$env:WATON_TEST_JID='628123456789@s.whatsapp.net'
$env:WATON_TEST_TEXT='test from waton'
python -u examples/live_connect.py

Bash:

export WATON_AUTH_DB='waton_live.db'
export WATON_TEST_JID='628123456789@s.whatsapp.net'
export WATON_TEST_TEXT='test from waton'
python -u examples/live_connect.py

If your account is already connected elsewhere, WhatsApp can return conflict disconnect code 440. This usually means another active linked session is competing. Keep only one active linked session during testing.

Contents