Sessions API | ActiWAPI

Manage WhatsApp sessions — create accounts, connect via QR, check status, and disconnect.

WhatsApp sessions are managed under `https://api.actiwapi.com/api/v1/whatsapp`. After creating a session, call connect and scan the QR code from the dashboard or Socket.io events.

GET/api/v1/whatsapp

List sessions

List all WhatsApp sessions for your tenant.

URL: https://api.actiwapi.com/api/v1/whatsapp

Auth: JWT Bearer

Headers

Header	Value	Required
Authorization	Bearer {accessToken}	Yes
Content-Type	application/json	Yes*

Query parameters

page — Page number (default 1)
limit — Items per page (default 20)

Code examples

curl -X GET "https://api.actiwapi.com/api/v1/whatsapp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"

Response example200

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Sales Line 1",
      "status": "connected",
      "phoneNumber": "919876543210",
      "connected": true
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}

Try in Swagger UI

POST/api/v1/whatsapp

Create session

Create a new WhatsApp session slot. Connect separately to obtain a QR code.

URL: https://api.actiwapi.com/api/v1/whatsapp

Auth: JWT Bearer

Headers

Header	Value	Required
Authorization	Bearer {accessToken}	Yes
Content-Type	application/json	Yes*

Request example

{ "name": "Support Line" }

Code examples

curl -X POST "https://api.actiwapi.com/api/v1/whatsapp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"
  -d '{ "name": "Support Line" }'

Response example201

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Support Line",
    "status": "disconnected",
    "phoneNumber": null
  }
}

Try in Swagger UI

POST/api/v1/whatsapp/{id}/connect

Connect session

Initiate QR code pairing for the session.

URL: https://api.actiwapi.com/api/v1/whatsapp/{id}/connect

Auth: JWT Bearer

Headers

Header	Value	Required
Authorization	Bearer {accessToken}	Yes
Content-Type	application/json	Yes*

Path parameters

id — Session UUID

Code examples

curl -X POST "https://api.actiwapi.com/api/v1/whatsapp/{id}/connect" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"

Response example200

{
  "success": true,
  "data": { "status": "qr_pending", "message": "Scan QR code in dashboard" }
}

Try in Swagger UI

GET/api/v1/whatsapp/{id}/status

Session status

Get real-time connection status for a session.

URL: https://api.actiwapi.com/api/v1/whatsapp/{id}/status

Auth: JWT Bearer

Headers

Header	Value	Required
Authorization	Bearer {accessToken}	Yes
Content-Type	application/json	Yes*

Path parameters

id — Session UUID

Code examples

curl -X GET "https://api.actiwapi.com/api/v1/whatsapp/{id}/status" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"

Response example200

{
  "success": true,
  "data": {
    "id": "uuid",
    "status": "connected",
    "phoneNumber": "919876543210",
    "connected": true
  }
}

Try in Swagger UI

POST/api/v1/whatsapp/{id}/disconnect

Disconnect session

Disconnect the WhatsApp session without deleting it.

URL: https://api.actiwapi.com/api/v1/whatsapp/{id}/disconnect

Auth: JWT Bearer

Headers

Header	Value	Required
Authorization	Bearer {accessToken}	Yes
Content-Type	application/json	Yes*

Path parameters

id — Session UUID

Code examples

curl -X POST "https://api.actiwapi.com/api/v1/whatsapp/{id}/disconnect" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"

Response example200

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

Try in Swagger UI

GET/api/external/sessions

List sessions (API key)

List sessions using API key authentication.

URL: https://api.actiwapi.com/api/external/sessions

Auth: API Key

Headers

Header	Value	Required
X-API-Key	{apiKey}	Yes
Content-Type	application/json	Yes*

Code examples

curl -X GET "https://api.actiwapi.com/api/external/sessions" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {apiKey}"

Response example200

{ "success": true, "data": [{ "id": "uuid", "status": "connected" }] }

Try in Swagger UI

Error codes

Failed requests return a JSON envelope with success: false and a human-readable message.

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "phone": "Valid phone number is required"
  }
}

HTTP	Code	Description
400	VALIDATION_ERROR	Request body or query failed validation.
401	UNAUTHORIZED	Missing or invalid JWT / API key.
403	FORBIDDEN	Authenticated but lacking permission or entitlement.
403	SUBSCRIPTION_INACTIVE	Trial expired or subscription not active.
403	LIMIT_EXCEEDED	Plan limit reached (sessions, messages, API requests, etc.).
404	NOT_FOUND	Resource does not exist or is not in your tenant.
409	CONFLICT	Duplicate resource or invalid state transition.
429	RATE_LIMITED	Too many requests; retry after backoff.
500	INTERNAL_ERROR	Unexpected server error.
502	WHATSAPP_UNAVAILABLE	WhatsApp session disconnected or provider error.

← Back to Getting Started