API reference

Sessions

Provision WhatsApp Web sessions, pair with a QR code, monitor warmth and connection health, and send a test message. Session count is limited by your plan.

Create a session, call connect, then scan the QR from the dashboard or listen for the Socket.io qr_generated event. You can list sessions at `https://api.actiwapi.com/api/v1/whatsapp` or the alias `https://api.actiwapi.com/api/sessions`. Pairing uses one socket owner per number so linked devices are not corrupted by duplicate connections.

Pair a number

Open WhatsApp on the phone → Linked devices → Link a device, then scan the QR. Keep the phone online. After pairing, the session status becomes connected and the phone number is stored on the session record.

  • POST /api/v1/whatsapp — create a named slot (counts against plan session limit).
  • POST /api/v1/whatsapp/{id}/connect — start pairing.
  • GET .../status or Socket.io qr_generated — show the QR until session_connected.
  • GET .../warmth — see whether the device is ready for bulk campaigns.

New linked devices should warm up with light conversation before large campaigns. ActiWAPI serializes sends per session and applies humanized delays.

GET/api/v1/whatsapp

List sessions

List all WhatsApp sessions for your account.

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

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

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

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

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

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

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

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

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

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

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

PATCH/api/v1/whatsapp/{id}

Rename session

Update the display name of a session slot.

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

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Path parameters

  • id — Session UUID

Request example

{ "name": "Support Line" }

Code examples

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

Response example200

{ "success": true, "data": { "id": "uuid", "name": "Support Line" } }

Try in Swagger UI

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

Session warmth

Device age, recent send volume, and campaign readiness for this linked number.

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

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Path parameters

  • id — Session UUID

Code examples

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

Response example200

{
  "success": true,
  "data": { "readyForCampaigns": false, "recommendation": "Warm up with light conversation first" }
}

Try in Swagger UI

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

Session logs

Recent connection and send events for debugging disconnects.

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

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Path parameters

  • id — Session UUID

Code examples

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

Response example200

{ "success": true, "data": [{ "at": "2026-09-03T12:00:00.000Z", "level": "info", "message": "connected" }] }

Try in Swagger UI

GET/api/v1/whatsapp/{id}/test-message

Test message preview

Preview the sample payload used by send-test.

URL: https://api.actiwapi.com/api/v1/whatsapp/{id}/test-message

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Path parameters

  • id — Session UUID

Code examples

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

Response example200

{ "success": true, "data": { "phone": "919876543210", "text": "ActiWAPI test message" } }

Try in Swagger UI

POST/api/v1/whatsapp/{id}/send-test

Send test message

Queue a small test send on this session (counts against daily message quota).

URL: https://api.actiwapi.com/api/v1/whatsapp/{id}/send-test

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Path parameters

  • id — Session UUID

Request example

{ "phone": "919876543210", "text": "ActiWAPI test message" }

Code examples

curl -X POST "https://api.actiwapi.com/api/v1/whatsapp/{id}/send-test" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"
  -d '{ "phone": "919876543210", "text": "ActiWAPI test message" }'

Response example202

{ "success": true, "data": { "id": "uuid", "status": "queued" } }

Try in Swagger UI

DELETE/api/v1/whatsapp/{id}

Delete session

Disconnect and permanently remove stored credentials. Prefer this over leaving ghost linked devices.

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

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Path parameters

  • id — Session UUID

Code examples

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

Response example200

{ "success": true, "data": { "id": "uuid", "deleted": true } }

Try in Swagger UI

GET/api/external/sessions

List sessions (API key)

Same list for integrations. Requires sessions:read. See External API for the full key-based surface.

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

Auth: API Key

Headers

HeaderValueRequired
X-API-Key{apiKey}Yes
Content-Typeapplication/jsonYes*

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"
  }
}
HTTPCodeDescription
400VALIDATION_ERRORRequest body or query failed validation.
401UNAUTHORIZEDMissing or invalid JWT / API key.
403FORBIDDENAuthenticated but lacking permission or entitlement.
403SUBSCRIPTION_INACTIVEAction not allowed on the current plan (including Free after trial). Upgrade or wait for entitlements.
403LIMIT_EXCEEDEDPlan limit reached (sessions, messages, API requests, etc.).
404NOT_FOUNDResource does not exist or is not in your account.
409CONFLICTDuplicate resource or invalid state transition.
429RATE_LIMITEDToo many requests; retry after backoff.
500INTERNAL_ERRORUnexpected server error.
502WHATSAPP_UNAVAILABLEWhatsApp session disconnected or provider error.