Skip to main content
A WaGo token is the stable identifier for one WhatsApp session. Create it once, store it in your own application database, and use that same token for connect, scan, messaging, webhook, and call requests. Token creation is an admin operation. Run it from your backend or deployment tooling only. Do not expose admintoken in browser code.

​
When to create a token

Create a token when:
  • A new customer, workspace, team, or device needs its own WhatsApp connection.
  • You are provisioning sessions before showing a QR code in your app.
  • You deleted a session with /session/delete and need to recreate it.
Do not create a new token every time the user opens your app. Reuse the existing token and call POST /session/connect to restore the session.

​
Request

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"
  }'

​
Fields

FieldRequiredMeaning
NameYesA human-readable name for the local WaGo user/session row. Keep it unique.
TokenYesThe session token your app will use in the token header. Spaces are removed before storage.
OsYesA label for the client environment, such as linux, chrome, server, or your product name.
Use tokens that are hard to guess. Treat session tokens like API credentials because anyone with a valid token can call session-level endpoints for that WhatsApp account.

​
Response

Successful creation returns a normal WaGo success envelope. The data value contains the created user details: 
{
  "code": 200,
  "data": {
    "details": "user created successfully",
    "name": "customer-1",
    "token": "customer-token-1",
    "osName": "linux"
  },
  "success": true
}
Store the token in your own database immediately after creation. Your app will need it for every later session request.

​
Duplicate tokens

If the Name or Token already exists, WaGo returns an error similar to: 
{
  "code": 500,
  "error": "token or name already exists",
  "success": false
}
When this happens, do not create a second token for the same user unless you intentionally want a separate WhatsApp session. Look up the existing token in your application database or list sessions with GET /session/all from a trusted admin backend.

​
Next step

After creating the token, connect it: 
curl -X POST http://localhost:1337/session/connect \
  -H "Content-Type: application/json" \
  -H "token: customer-token-1" \
  -d '{
    "Subscribe": ["Message", "ReadReceipt", "Presence", "Call"],
    "Immediate": true,
    "Phone": ""
  }'
Then fetch /session/qr and show the QR code to the user. See Connect and scan for the full flow.