Skip to main content
A WaGo session is one WhatsApp device connection controlled by one session token. Most application endpoints require the session to be connected and logged in.

​
Lifecycle

  1. Admin creates or already has a token.
  2. Client calls POST /session/connect with that token.
  3. If the device is not logged in, client calls GET /session/qr.
  4. User scans the QR code in WhatsApp linked devices.
  5. Client polls GET /session/status until Connected and LoggedIn are true.
  6. The same token can later restore the session by calling POST /session/connect again.

​
Endpoints

EndpointAuthBodyUse
POST /session/initadmintokenName, Token, OsCreate a token row in the local database.
POST /session/connecttokenSubscribe, Immediate, PhoneStart or restore a WhatsApp client for the token.
POST /session/pairtokenSubscribe, Immediate, PhoneConnect using a WhatsApp pair code flow.
GET /session/qrtokennoneReturn the current QR code as a data URL.
GET /session/statustokennoneReturn connection and login state.
POST /session/disconnecttokennoneDisconnect from WhatsApp without logging out the linked device.
POST /session/logouttokennoneLog out from WhatsApp. A future connection requires scanning again.
GET /session/alladmintokennoneList stored users, tokens, webhooks, and JIDs.
POST /session/deleteadmintoken plus target tokennoneDelete a token and local session files.
POST /session/scannedadmintokennoneReturn sessions that already have a JID stored.

​
Create a token

For the full admin provisioning flow, see Create a token. 
curl -X POST http://localhost:1337/session/init \
  -H "Content-Type: application/json" \
  -H "admintoken: YOUR_ADMIN_TOKEN" \
  -d '{
    "Name": "customer-1",
    "Token": "customer-token-1",
    "Os": "linux"
  }'
Token is stored after spaces are removed. Keep it stable because it identifies the session in later requests.

​
Connect a token

curl -X POST http://localhost:1337/session/connect \
  -H "Content-Type: application/json" \
  -H "token: YOUR_TOKEN" \
  -d '{
    "Subscribe": ["Message", "ReadReceipt", "Presence", "Call"],
    "Immediate": true,
    "Phone": ""
  }'
Subscribe controls webhook event classes. Valid values in code are: 
Message, ReadReceipt, Presence, HistorySync, ChatPresence, Call, All, Newsletter, LoggedOut
Use ["All"] while testing. In production, subscribe only to events your app uses.

​
Scan QR

curl -H "token: YOUR_TOKEN" \
  http://localhost:1337/session/qr
Render QRCode as an image. If the session is already logged in, the endpoint returns an error instead of a QR.

​
Restore a session

To restore after process restart, call POST /session/connect with the same token. If WhatsApp credentials are still valid on disk, WaGo reconnects without a QR scan.

​
Disconnect vs logout

ActionKeeps WhatsApp linked?Next connect needs QR?
POST /session/disconnectYesUsually no
POST /session/logoutNoYes
POST /session/deleteRemoves local token/sessionToken must be recreated
Use disconnect for maintenance. Use logout when the user wants to unlink the device.