Sessions

A channel is a database row in our system. A session is the live WhatsApp connection that backs it. While the channel is connected, the two are 1:1 — but they have different lifecycles.

What a session is

Under the hood, each connected channel holds the cryptographic state that makes the connection "yours" — the same primitives the official WhatsApp Web client uses. We persist that state on the gateway side so a process restart can resume the channel without forcing a fresh QR scan.

You don't manage any of this directly. From your application's perspective there's just the channel: it's connected or it isn't.

Why sessions can drop

Three things will move a channel out of connected:

1. Network blip. The connection drops, the gateway transitions the channel to reconnecting, and resumes from the persisted state. Usually invisible.

2. The user revokes the session. Common causes:

   • The user signed out from the phone's Linked devices screen.
   • The user signed in from another WhatsApp Web client and the platform rotated keys.

   When that happens the persisted state is invalidated, the channel moves to disconnected, and a new QR scan is required.

3. Gateway restart. The persisted state survives on disk, so the next boot resumes seamlessly. Any in-flight outbound sends queue up and resume on resume — see Concepts → Webhooks → Retries for what that means in practice.

What you'll see

The dashboard subscribes to /v1/events and renders these transitions live. A channel stuck in reconnecting for more than ~30 seconds is unusual and surfaces a banner so you notice without polling. Your application receives the same information via the channel.connected and channel.disconnected webhooks.