Event Model

Event Model#

Waton exposes two inbound streams at low level:

  1. client.on_message(node) for raw protocol nodes.

  2. client.on_event(event_dict) for normalized events.

If you need stable event categories for app logic, prefer on_event.

Normalized event categories#

The normalizer classifies incoming node tags and emits event dictionaries. Common event type values include:

Message and content:

  • messages.upsert

  • messages.reaction

  • messages.reaction_encrypted

  • messages.poll_update_encrypted

  • messages.event_response_encrypted

Protocol-derived message events:

  • messages.revoke

  • messages.edit

  • messages.ephemeral_setting

  • messages.history_sync

  • messages.app_state_sync_key_share

  • messages.group_member_label_change

  • messages.protocol (fallback)

Receipts and retry:

  • messages.receipt

  • messages.retry_request

  • messages.retry_request_sent

Notifications, calls, and ack lane:

  • messages.notification

  • messages.call

  • messages.ack

  • messages.bad_ack

  • messages.protocol_notification

Payload shape (high-level)#

Event payloads are dictionaries and vary by type. Typical keys:

  • message events: {"type": ..., "message": {...}}

  • receipt events: {"type": ..., "receipt": {...}}

  • notification events: {"type": ..., "notification": {...}}

  • ack events: {"type": ..., "ack"|"bad_ack": {...}}

  • call events: {"type": "messages.call", "call": {...}}

Ordering and buffering#

Waton can prioritize incoming lanes when buffering is enabled:

  1. receipt

  2. notification

  3. call

  4. ack

  5. ib

  6. message

  7. other

This behavior is controlled by:

  • enable_offline_node_buffer

  • incoming_node_buffer_size

  • incoming_node_yield_every

Tip: if your business logic depends on strict ordering, document and test with this buffering behavior in mind.

High-level App note#

App only routes message nodes to handler decorators. For full normalized event coverage, attach listeners directly to WAClient.

Next steps#

Contents