> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions & Connection Lifecycle

> How GOWA stores WhatsApp sessions, reconnects after restarts, and what logout and removal do.

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

```mermaid theme={null}
flowchart LR
  A[POST /devices] --> B[disconnected]
  B -->|login: QR / pairing code| C[connected]
  C -->|scan or code accepted| D[logged_in]
  D -->|network drop| E[connecting]
  E --> D
  D -->|logout from GOWA or phone| B
  B -->|DELETE /devices/id| F[removed]
```

| 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:

```bash theme={null}
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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.