Sessions

Manage WhatsApp sessions. Each session represents a connected WhatsApp account.

Create Session

Creates a new session and automatically starts connecting to WhatsApp.

POST /api/v1/sessions

Request Body

{
  "id": "my-session",
  "name": "My Business Account",
  "webhook": {
    "url": "https://example.com/webhook",
    "events": ["message", "connected"],
    "secret": "webhook-secret"
  },
  "device": {
    "os": "Windows",
    "platform": "desktop"
  }
}

Field	Type	Required	Description
id	string	No	Custom session ID (auto-generated if not provided)
name	string	No	Friendly name for the session
webhook	object	No	Webhook configuration
webhook.url	string	Yes*	Webhook URL
webhook.events	array	No	Events to subscribe (default: all)
webhook.secret	string	No	HMAC secret for signature verification
device	object	No	Per-session device identity override (see Device Identity)
device.os	string	No	OS label shown in WhatsApp Linked Devices, e.g. Windows, Mac OS X, Ubuntu
device.platform	string	No	Platform type — see table in Device Identity
device.version	string	No	Dotted app version, e.g. 2.3000.1023902713. Omit to use library default

Response

{
  "session": {
    "id": "my-session",
    "name": "My Business Account",
    "phone_number": null,
    "push_name": null,
    "status": "connecting",
    "created_at": 1767143203,
    "updated_at": 1767143203,
    "last_connected_at": null,
    "is_logged_in": false
  }
}

Example

curl -X POST http://localhost:3451/api/v1/sessions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "business-1",
    "name": "Business Account",
    "webhook": {
      "url": "https://example.com/webhook"
    }
  }'

---

List Sessions

Get all sessions.

GET /api/v1/sessions

Response

{
  "sessions": [
    {
      "id": "my-session",
      "name": "My Account",
      "status": "logged_in",
      "is_logged_in": true
    }
  ],
  "total": 1
}

---

Get Session

Get a specific session by ID.

GET /api/v1/sessions/{session_id}

Response

{
  "id": "my-session",
  "name": "My Account",
  "phone_number": "628123456789",
  "push_name": "John Doe",
  "status": "logged_in",
  "is_logged_in": true
}

---

Delete Session

Delete a session and disconnect from WhatsApp.

DELETE /api/v1/sessions/{session_id}

Cascade behaviour

Session delete cascades on both storage layers:

• DB rows — child rows in webhooks, contacts, and webhook_dlq scoped to this session_id are dropped explicitly before the sessions row is removed. This runs even on databases whose tables were migrated in without an ON DELETE CASCADE constraint, so no orphans are left behind.
• In-memory registry — every webhook registration pointing at this session is removed from the dispatcher, along with any open circuit state for those URLs.
• Storage directory — the on-disk session store under WHATSAPP_STORAGE_PATH/{session_id} is unlinked.

Response

{
  "success": true,
  "message": "Session deleted"
}

---

Get Session Status

Get current connection status.

GET /api/v1/sessions/{session_id}/status

Response

{
  "status": "logged_in",
  "is_logged_in": true,
  "phone_number": "628123456789",
  "push_name": "John Doe"
}

Status Values

Status	Description
disconnected	Not connected
connecting	Establishing connection
waiting_for_qr	Waiting for QR code scan
waiting_for_pair_code	Waiting for pair code entry
connected	Connected but not logged in
logged_in	Fully authenticated

---

Get QR Code

Get QR codes for authentication.

GET /api/v1/sessions/{session_id}/qr

Response

{
  "qr_codes": ["2@ABC123..."],
  "timeout_seconds": 60,
  "status": "waiting_for_qr"
}

---

Connect Session

Manually trigger connection (usually not needed as create auto-connects).

POST /api/v1/sessions/{session_id}/connect

Request Body (optional)

Accepts an optional device identity override. Same shape as device in Create Session. The override only takes effect on the first successful pair — subsequent reconnects reuse the props that whatsapp-rust persisted at pair time.

{
  "device": {
    "os": "Windows",
    "platform": "desktop"
  }
}

Empty body is fine — falls back to environment defaults (WA_DEVICE_OS, WA_DEVICE_PLATFORM, WA_DEVICE_VERSION).

---

Pair with Phone Number

Connect using pair code instead of QR.

POST /api/v1/sessions/{session_id}/pair

Request Body

{
  "phone_number": "+628123456789",
  "show_push_notification": true,
  "device": {
    "os": "Windows",
    "platform": "desktop"
  }
}

device is optional. See Device Identity for the field schema and the available platform values.

Response

{
  "code": "ABCD-EFGH",
  "timeout_seconds": 60
}

---

Disconnect Session

Disconnect from WhatsApp without deleting the session.

POST /api/v1/sessions/{session_id}/disconnect

---

Get Device Info

Get connected device information.

GET /api/v1/sessions/{session_id}/device

Response

{
  "device_id": 1,
  "phone_number": "628123456789",
  "lid": "123456789@lid",
  "push_name": "John Doe"
}

---

Device Identity

Controls how each session appears in WhatsApp's Linked Devices list at pair time (the OS string + platform icon). The default is Windows / desktop, which displays as WhatsApp Desktop rather than a browser client.

Where it applies

• POST /api/v1/sessions — device field in the create body
• POST /api/v1/sessions/{id}/connect — optional body with a device field
• POST /api/v1/sessions/{id}/pair — device field alongside phone_number

Important caveat

Device props are only honored on the first pair. Once a device is registered with WhatsApp, the gateway persists the props in its SQLite store and reuses them on every reconnect. To change the identity of an already-paired session, delete it and pair again.

Field schema

Field	Type	Default	Description
os	string	Windows	Free-form OS label shown in WA
platform	string	desktop	One of the platform values below
version	string	library default	Dotted version like 2.3000.1023902713. Leave unset unless you have a specific reason — forcing a version has been observed to cause silent server-side drops on freshly-paired sessions.

Platform values

Value	Linked Devices icon
desktop	WhatsApp Desktop (default)
uwp	Windows Store app
chrome	Google Chrome
firefox	Mozilla Firefox
edge	Microsoft Edge
safari	Safari
opera	Opera
ie	Internet Explorer
ipad	iPad
ios_phone	iPhone
android_phone	Android Phone
android_tablet	Android Tablet

Unknown values fall back to desktop.

Environment fallback

When no device field is sent, the gateway falls back to these env vars:

WA_DEVICE_OS=Windows
WA_DEVICE_PLATFORM=desktop
WA_DEVICE_VERSION=               # omit for library default