Waton Documentation

WhatsApp Multi-Device Python SDK

Build WhatsApp workflows with a modern Python-first stack.

Waton combines high-level DX with Rust-backed crypto internals so you can move fast without sacrificing protocol fidelity. From quickstart to production operations, this docs site is structured as a practical developer portal.

• GitHub Repository

• Getting Started

• App Quickstart

• Troubleshooting

Note

Best path for new users: Start with Getting Started, then continue to Quickstart: App (Recommended) for the first production-style integration.

Start Here Setup, first run, and dashboard-assisted development.	Core Concepts Architecture, lifecycle, events, and message model fundamentals.
How-to Guides Practical workflows from handling messages to group operations.	Reference Configuration and API references when you need exact details.

Start Here

• Getting Started
  • Requirements
  • Install
  • Fastest bot start (simple callback API)
  • First connection test
  • Optional message send test
• Quickstart: App (Recommended)
  • Prerequisites
  • Install
  • Create a minimal bot
  • Run
  • Expected flow
  • Useful notes
  • Next steps
• Quickstart: Low-Level WAClient
  • Prerequisites
  • Install
  • Minimal client example
  • Run
  • Expected output
  • When to use WAClient directly
  • Next steps
• Browser Dashboard (Devtool)
  • Install dependency
  • Run dashboard
  • Security note
  • API endpoints
  • Validation behavior
  • Useful for
  • Expected connection flow
  • WhatsApp Web style layout

Core Concepts

• Core Concepts
  • Architecture at a glance
  • Message model
  • App vs WAClient: when to use which
  • Important limitation in high-level mode
  • Next steps
• Connection Lifecycle
  • Connection states
  • Typical flow
  • Minimal callback example
  • Reconnect behavior
  • Keepalive and timeouts
  • High-level App behavior
  • Next steps
• Event Model
  • Normalized event categories
  • Payload shape (high-level)
  • Ordering and buffering
  • High-level App note
  • Next steps
• Message Model
  • Parsed Message fields
  • Content type extraction
  • Encrypted add-ons and message secrets
  • LID/PN handling notes
  • Practical recommendation
  • Next steps

How-to Guides

• Handling Messages
  • Basic handler flow
  • Filters
  • Context helpers
  • Middleware
  • Message content model
  • Important scope note
  • Next steps
• Sending Messages
  • Quick start
  • Core send methods
  • Advanced methods
  • Read/receipt utilities
  • Minimal example
  • Reliability notes
  • Next steps
• Group Management
  • Implemented capabilities
  • Example
  • Important notes
  • Receiving group updates
  • Next steps
• Privacy and Chats
  • Chat operations
  • Privacy operations
  • Current support status
  • Example
  • Presence helper API
  • Next steps
• App State and History Sync
  • Protocol side effects
  • Message secret persistence
  • Related normalized event types
  • Support status
  • Practical guidance
  • Next steps
• Business and Newsletters
  • Business-related behavior
  • Newsletter API
  • Newsletter events
  • Support status notes
  • Example
  • Next steps

Reference

• Configuration Reference
  • Source of truth
  • Connection and protocol defaults
  • Timeouts and intervals
  • Reconnect behavior
  • Incoming handling/reliability
  • App-state/message-secret cache
  • Incoming node buffering
  • Call behavior
  • Minimal override example
  • Recommendations
  • Next steps
• App Framework Reference
  • App class
  • Decorators and hooks
  • Middleware
  • Router behavior
  • Context reference
  • Lifecycle
  • Notes
  • Next steps
• Client API Reference
  • WAClient
  • MessagesAPI
  • GroupsAPI
  • ChatsAPI
  • PresenceAPI
  • NewsletterAPI
  • Support status guidance
  • Next steps
• Dashboard API Reference
  • Base URL
  • Core endpoints
  • /api/send request
  • Minimal curl smoke tests
  • Notes
  • Next steps

Support & Operations

• Testing Waton
  • Unit tests
  • Live reliability check
  • Release preflight
  • Docs verification
  • Windows editable install lock issue
• FAQ and Troubleshooting
  • I cannot send via dashboard
  • I get invalid WA ID errors
  • QR is not shown
  • Disconnect conflict code 440
  • Ack timeout on live send test
  • Editable install fails on Windows (os error 32)
  • Docs build fails
  • If page is missing in nav
  • Useful verification commands
• Migration and Compatibility
  • Runtime compatibility
  • Configuration compatibility
  • Message/event compatibility
  • API compatibility note
  • Migration checklist for apps
  • Suggested validation commands
  • Release notes and changes
• Read the Docs Setup
  • Project import steps
  • Build configuration used
  • Local verification before pushing
  • Operational checklist
  • Troubleshooting