API Documentation

WhatsApp Sessions

Sessions are required to connect to WhatsApp and send/receive messages.

Session Management

Each WhatsApp connection requires a session. Sessions persist until explicitly disconnected or timed out.

Create Session

POST /api/v1/sessions

Creates a new WhatsApp session and returns a QR code for scanning with your WhatsApp mobile app.

Request Parameters

Parameter Type Required Description
name string Optional Custom name for the session

Response

{
  "success": true,
  "data": {
    "sessionId": "session_123abc",
    "qrCode": "data:image/png;base64,...",
    "status": "pending"
  }
}

cURL Example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-whatsapp-session"}' \
  https://api.messaging.com/v1/sessions

Get Session Status

GET /api/v1/sessions/{sessionId}

Retrieves the current status of a WhatsApp session.

Path Parameters

Parameter Type Required Description
sessionId string Required ID of the session to check

Response

{
  "success": true,
  "data": {
    "sessionId": "session_123abc",
    "status": "connected",
    "name": "my-whatsapp-session",
    "createdAt": "2025-09-14T15:30:00Z",
    "lastActivity": "2025-09-14T15:35:00Z"
  }
}

cURL Example

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.messaging.com/v1/sessions/session_123abc

Delete Session

DELETE /api/v1/sessions/{sessionId}

Disconnects and removes a WhatsApp session.

Path Parameters

Parameter Type Required Description
sessionId string Required ID of the session to delete

Response

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

cURL Example

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.messaging.com/v1/sessions/session_123abc

List All Sessions

GET /api/v1/sessions

Retrieves a list of all your WhatsApp sessions.

Query Parameters

Parameter Type Required Description
limit integer Optional Maximum number of sessions to return (default: 10)
offset integer Optional Number of sessions to skip (default: 0)
status string Optional Filter by session status (connected, disconnected, pending)

Response

{
  "success": true,
  "data": {
    "sessions": [
      {
        "sessionId": "session_123abc",
        "status": "connected",
        "name": "my-whatsapp-session",
        "createdAt": "2025-09-14T15:30:00Z",
        "lastActivity": "2025-09-14T15:35:00Z"
      },
      {
        "sessionId": "session_456def",
        "status": "disconnected",
        "name": "second-session",
        "createdAt": "2025-09-13T10:00:00Z",
        "lastActivity": "2025-09-13T12:00:00Z"
      }
    ],
    "total": 2,
    "limit": 10,
    "offset": 0
  }
}

cURL Example

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.messaging.com/v1/sessions?status=connected

Session States

A WhatsApp session can be in one of the following states:

  • pending: Session created, waiting for QR code scan
  • connected: Successfully connected to WhatsApp
  • disconnected: Session was disconnected
  • timeout: QR code expired without being scanned
  • error: An error occurred with the session

Session Limits

The number of concurrent sessions you can create depends on your subscription plan:

Plan Maximum Sessions
Free 1
Basic 5
Premium 20
Enterprise Unlimited