Sessions

An instance is a database row. A session is the live WhatsApp Web connection that backs it. They have a 1:1 relationship while the instance is connected, but they have very different lifecycles.

What a session is

Under the hood, each connected instance holds:

A noiseKey keypair, a signedIdentityKey, a signedPreKey, and a fistful of other Signal-protocol material — the same primitives the official WhatsApp Web client uses.
A persistent WebSocket to a WhatsApp server.
A locally-stored creds.json plus a directory of session keys, one file per chat partner.

This material is what makes the session "yours". If you copy it to another machine, that machine can resume the WhatsApp Web tab without scanning a new QR. If you lose it, you scan a new QR.

Where it's stored

By default, auth-state lives at data/sessions/<instance-id>/. The SocketFactory interface in the backend abstracts this — production deploys swap to a Redis-backed adapter so workers can be stateless, but the disk-backed adapter is the default and is fine for single-binary deploys.

Treat the auth-state directory like a credential. Anyone with read access to it can pose as your WhatsApp account from a different machine. Don't bake it into a container image; mount it from a persistent volume that's not in your image build.

Why sessions die

Three reasons a session goes from connected to something else:

Network blip. The WebSocket drops. The session manager detects the close, transitions the instance to reconnecting, and tries to resume with the persisted auth-state. Usually invisible to the user.
sessionInvalidated. WhatsApp explicitly tells us the session is dead. Common causes:
- The user logged out from the Linked devices screen on their phone.
- The user logged in from another Web client and WhatsApp rotated keys.
- A Baileys protocol mismatch (rare; track upstream releases).
The auth-state is wiped, the instance moves to disconnected, and a new QR scan is required.
Process crash / pod evict. The auth-state survives on disk, so the next process boot resumes seamlessly. But any in-flight outbound sends are at the queue's mercy — see Concepts → Webhooks → Retries for what that means in practice.

What you'll see in the dashboard

The dashboard subscribes to /v1/events and renders these transitions live. A session in reconnecting for more than ~30 seconds is unusual and is what the heartbeat job watches for; the dashboard will surface a banner if any of your instances are stuck there.