Connection Lifecycle

Connection Lifecycle#

This page explains how Waton connects, authenticates, and disconnects.

Connection states#

WAClient emits connection updates via client.on_connection_update. Current status values emitted by the implementation include:

  • connecting

  • pairing-success

  • pairing-signed

  • open

  • close

The event object is ConnectionEvent with:

  • status

  • qr (optional)

  • reason (optional)

Typical flow#

  1. connect() is called.

  2. Status becomes connecting.

  3. If credentials are not ready, QR values are emitted (still connecting).

  4. After successful auth and stream success, status becomes open.

  5. On disconnect/error, status becomes close with reason.

Minimal callback example#

async def on_connection_update(event):
    print(f"status={event.status}")
    if event.qr:
        print("QR received")
    if event.reason:
        print(f"reason={event.reason}")

Reconnect behavior#

Reconnect-related behavior is controlled through configuration values in DEFAULT_CONNECTION_CONFIG:

  • auto_restart_on_515

  • max_restart_attempts

These are used to decide whether restart-required disconnects should trigger automatic reconnect attempts.

Keepalive and timeouts#

Important connection-related config keys:

  • connect_timeout

  • frame_timeout

  • keepalive_interval

  • qr_timeout

If you tune these values, keep conservative defaults for production stability.

High-level App behavior#

App.run() wraps this lifecycle:

  1. Calls client.connect()

  2. Waits until connection status is open

  3. Runs optional @app.on_ready callback

  4. Keeps loop alive until shutdown

If QR rendering package is installed, App prints terminal QR automatically.

Next steps#

Contents