Core Concepts

Core Concepts#

This page explains the core building blocks of Waton before you dive into APIs.

Architecture at a glance#

Waton has two main layers:

  1. High-level App API - App gives decorator-based handlers (@app.message(...)) and context helpers (ctx.reply(...)). - Best for bot development and application logic.

  2. Low-level WAClient API - WAClient handles transport, authentication, protocol nodes, and normalized events. - Best for advanced control, custom pipelines, and protocol-level debugging.

Supporting APIs (available from App):

  • MessagesAPI for sending messages

  • GroupsAPI for group operations

  • ChatsAPI for profile/privacy/chat modifications

  • NewsletterAPI for channel/newsletter features

  • PresenceAPI for presence updates

Message model#

Incoming messages are parsed into a rich Message entity with fields such as:

  • identity: id, from_jid, participant

  • text/media: text, media_url

  • protocol updates: protocol_type, target_message_id, edited_text

  • advanced encrypted add-ons: poll_update, event_response, encrypted_reaction

  • content metadata: content_type, content, message_secret_b64

This model is what Context.message exposes in App handlers.

App vs WAClient: when to use which#

Use App when:

  • You want fast bot development with decorators and filters.

  • You mostly care about message handling and replies.

Use WAClient when:

  • You need normalized events from receipts/notifications/calls/acks.

  • You need detailed lifecycle control and protocol-level visibility.

Important limitation in high-level mode#

App dispatches only nodes tagged message into router handlers. Non-message node types (for example receipt/notification/call/ack/ib) are not routed via @app.message handlers. For those, use low-level client.on_event.

Next steps#

Contents