Sessions & Connection Lifecycle

A session is the cryptographic identity WhatsApp issues when you pair a device slot. GOWA keeps it in its database, so a slot stays linked across restarts until it is logged out from GOWA or from the phone.

Lifecycle

Event	What GOWA does
Server start	Loads every slot and, about 2 seconds after boot, reconnects the ones with a stored session.
Connection lost	whatsmeow reconnects automatically. A background check also runs every 5 minutes and reconnects a dropped client.
Manual reconnect	`POST /devices/{device_id}/reconnect` or `GET /app/reconnect`.
Logout	`POST /devices/{device_id}/logout` or `GET /app/logout`. Unlinks from WhatsApp, deletes the session keys, keeps the slot.
Unlinked from the phone	Same as logout: the slot remains and must be paired again.
Removal	`DELETE /devices/{device_id}`. Logs out, then deletes the slot and its chat data.

Check a slot at any time:

curl -u admin:changeme http://localhost:3000/devices/my-device/status

is_connected reflects the socket; is_logged_in reflects whether the session is valid. Both must be true to send.

Where sessions are stored

Setting	Default	Contents
`DB_URI`	`file:storages/whatsapp.db`	whatsmeow device store: identity keys, sessions, contacts. SQLite or PostgreSQL (`postgres://...`).
`DB_KEYS_URI`	empty (uses `DB_URI`)	Optional separate database for the encryption key cache. Avoid in-memory storage in production; a restart would lose session state.
(fixed)	`file:storages/chatstorage.db`	Device registry, chat and message history, scheduled sends, Chatwoot links.

Anyone with these files can act as the linked accounts. Restrict file permissions and encrypt backups.

Back up and restore

Stop GOWA (or snapshot the volume), then copy storages/. With PostgreSQL for DB_URI, back up that database and storages/chatstorage.db together. Restoring both brings every slot back without pairing again. Do not run two GOWA instances against the same session data. WhatsApp sees two clients with one identity and disconnects one of them.

Presence

Setting	Default	Effect
`WHATSAPP_PRESENCE_ON_CONNECT`	`unavailable`	Presence sent after connecting: `available`, `unavailable` or `none`.
`WHATSAPP_PRESENCE_PULSE_ENABLED`	`true`	Periodically marks the account `available` for a short window, then `unavailable` again.
`WHATSAPP_PRESENCE_PULSE_INTERVAL`	`24h`	Time between pulses.
`WHATSAPP_PRESENCE_PULSE_DURATION`	`5m`	How long each pulse stays `available`.

Set presence manually with POST /send/presence ({"type": "available"} or "unavailable").

Troubleshooting

Symptom	Likely cause	Fix
`is_logged_in: false` after a restart	Session was unlinked from the phone, or `storages/` was not persisted.	Mount `/app/storages` as a volume; pair again.
Slot keeps disconnecting	Another process uses the same session, or the phone has been offline for about 14 days.	Run a single instance; open WhatsApp on the phone.
QR expires before scanning	`qr_duration` elapsed.	Call the login endpoint again, or use a pairing code.
Sends fail with “not logged in”	Slot exists but is not paired.	Check `/devices/{device_id}/status`; pair again.

Getting Started

Core Concepts

Usage Examples

Integrations

Advanced

Lifecycle

Where sessions are stored

Back up and restore

Presence

Troubleshooting

​Lifecycle

​Where sessions are stored

​Back up and restore

​Presence

​Troubleshooting

Lifecycle

Where sessions are stored

Back up and restore

Presence

Troubleshooting