Sessions
One OpenWA session per workspace, how it is created and linked, and what each status means.
Lifecycle
POST /admin/session/connect on the engine creates the workspace's session (or reuses it), registers the webhook, and starts the session. It stores session_id, session_name and the last reported session_status on channel_connection, plus a channel_route row that maps the session to the workspace. The admin app then polls session/qr until the owner links a phone.
| Engine admin endpoint | Effect |
|---|---|
POST /admin/session/connect | Create or reuse the session, ensure the webhook, start it. |
POST /admin/session/qr | Returns a PNG data URL for the QR code, or the phone number once ready. |
POST /admin/session/pairing-code | Requests a pairing code for a phone number (digits only). |
POST /admin/session/status | Syncs and returns the current status. |
POST /admin/session/logout | Unlinks the device, marks the connection disconnected and evicts the route cache. |
Linking a phone
Either method works with a regular WhatsApp or a WhatsApp Business app account. On the phone open WhatsApp, Settings, Linked devices, Link a device.
- QR code. Scan the code shown in the admin app. Codes rotate, so the page keeps polling.
- Pairing code. Choose Link with phone number instead, enter the number in the admin app, then type the code it shows into WhatsApp.
The linked account keeps working on the phone. Staff can reply from the phone too (see Operations).
Session status values
| Status | Meaning |
|---|---|
created | Session exists, not started. |
initializing | Chromium is starting. |
qr_ready | A QR code or pairing code can be used. |
authenticating | The phone accepted the link. |
ready | Linked and able to send. The connection becomes active. |
disconnected | The link is gone. |
action_required | The gateway needs operator attention. |
failed | The session could not start. |
The connection status (pending, active, paused, disconnected) is separate. It becomes active when the session reports ready or session.authenticated. A session.disconnected event only sets the connection to disconnected when the reason matches logout, unpair, unlink, conflict or banned (the device needs a new scan). Other disconnect reasons are transient and the gateway reconnects on its own.