Session Management

Manage WhatsApp sessions, including creating, starting, stopping, and deleting sessions.

Create Session

Creates a new WhatsApp session and returns a unique API key.

POST /sessions/create

Request Body

Parameter	Type	Required	Description
name	string	Yes	Unique name for the session
webhookUrl	string	No	URL to receive webhook events
metadata	object	No	Custom metadata for the session

Example Request

curl -X POST http://localhost:3000/sessions/create \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-session",
    "webhookUrl": "https://your-server.com/webhook",
    "metadata": {
      "userId": "123",
      "plan": "premium"
    }
  }'

Response

{
  "success": true,
  "session": {
    "id": "e67a00be-ed45-4356-9488-049cabb9895d",
    "name": "my-session",
    "state": "starting",
    "createdAt": "2026-01-28T10:00:00.000Z"
  },
  "apiKey": "wask_d5726b79a64573672bd70fa06f3632ea3c6af7781588d98e",
  "warning": "IMPORTANT: Save this API key securely! It will NOT be shown again."
}

Important

Save the apiKey immediately! It will never be shown again. If you lose it, you'll need to delete the session and create a new one.

---

Get QR Code

Get the QR code to scan with WhatsApp mobile app.

GET /sessions/{id}/qr

Headers

Header	Value
X-API-Key	Your session API key

Example Request

curl -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/qr

Response

{
  "success": true,
  "qr": "2@ABC123...base64_qr_string"
}

States When QR is Available

• qr_ready - QR code is ready to scan
• starting - Session is initializing, QR not yet available

---

Get Session Status

Get the current status of a session.

GET /sessions/{id}/status

Headers

Header	Value
X-API-Key	Your session API key

Example Request

curl -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/status

Response

{
  "success": true,
  "session": {
    "id": "e67a00be-ed45-4356-9488-049cabb9895d",
    "name": "my-session",
    "state": "ready",
    "phoneNumber": "919878695378",
    "createdAt": "2026-01-28T10:00:00.000Z",
    "lastActivity": "2026-01-28T10:05:00.000Z"
  }
}

Session States

State	Description
creating	Session is being created
starting	Container is starting
qr_ready	QR code available for scanning
connecting	Connecting to WhatsApp
ready	✅ Authenticated and ready to send/receive
disconnected	Temporarily disconnected (will auto-reconnect)
failed	Failed to connect
stopped	Manually stopped
logged_out	Logged out from WhatsApp

---

List All Sessions

List all sessions (requires admin key).

GET /sessions

Headers

Header	Value
X-API-Key	Your admin API key

Example Request

curl -H "X-API-Key: wamk_your_admin_key" \
  http://localhost:3000/sessions

Response

{
  "success": true,
  "sessions": [
    {
      "id": "e67a00be-ed45-4356-9488-049cabb9895d",
      "name": "my-session",
      "state": "ready",
      "phoneNumber": "919878695378",
      "createdAt": "2026-01-28T10:00:00.000Z"
    }
  ]
}

---

Stop Session

Stop a running session (container will be stopped but not deleted).

POST /sessions/{id}/stop

Headers

Header	Value
X-API-Key	Your session API key

Example Request

curl -X POST \
  -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/stop

Response

{
  "success": true,
  "message": "Session stopped successfully"
}

---

Start Session

Start a stopped session.

POST /sessions/{id}/start

Headers

Header	Value
X-API-Key	Your session API key

Example Request

curl -X POST \
  -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/start

Response

{
  "success": true,
  "message": "Session started successfully"
}

---

Delete Session

Permanently delete a session and its container.

DELETE /sessions/{id}

Headers

Header	Value
X-API-Key	Your session API key

Example Request

curl -X DELETE \
  -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d

Response

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

Warning

This action is irreversible. All session data will be permanently deleted.

---

Logout Session

Logout from WhatsApp (requires re-scanning QR code to reconnect).

POST /sessions/{id}/logout

Headers

Header	Value
X-API-Key	Your session API key

Example Request

curl -X POST \
  -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/logout

Response

{
  "success": true,
  "message": "Session logged out successfully"
}

---

Check Number Exists

Check if a phone number is registered on WhatsApp.

GET /sessions/{id}/check-number/{phone}

Headers

Header	Value
X-API-Key	Your session API key

Path Parameters

Parameter	Type	Description
phone	string	Phone number with country code

Example Request

curl -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/check-number/919988066776

Response

{
  "success": true,
  "exists": true,
  "jid": "919988066776@s.whatsapp.net"
}

---

Get All Contacts

Get all contacts synced from the linked WhatsApp account.

GET /sessions/{id}/contacts

Headers

Header	Value
X-API-Key	Your session API key

Example Request

curl -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/contacts

Response

{
  "success": true,
  "contacts": [
    {
      "id": "919988066776@s.whatsapp.net",
      "name": "John Doe",
      "notify": "John",
      "verifiedName": null,
      "phone": "919988066776"
    }
  ]
}

---

Get All Chats

Get all chats (individual and group).

GET /sessions/{id}/chats

Headers

Header	Value
X-API-Key	Your session API key

Example Request

curl -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/chats

Response

{
  "success": true,
  "chats": [
    {
      "id": "919988066776@s.whatsapp.net",
      "name": "John Doe",
      "isGroup": false,
      "unreadCount": 2,
      "timestamp": 1706443200
    },
    {
      "id": "120363123456789@g.us",
      "name": "Family Group",
      "isGroup": true,
      "unreadCount": 0,
      "timestamp": 1706443100
    }
  ]
}