Sessions | Tusk WhatsApp API

List sessions

GET/v1/whatsapp/sessions

Returns every session on your account.

curl "https://api.tuskmail.africa/v1/whatsapp/sessions" \
  -H "X-API-Key: $TUSK_WA_KEY"

200 OK

{
  "data": [
    {
      "id": "9c1f6a4e-2b7d-4e0a-8f53-6d2a1b7c9e10",
      "name": "Sales",
      "phone": "254700000001",
      "status": "ready",
      "status_label": "Ready",
      "active": true,
      "created_at": "2026-01-15T09:30:00Z"
    }
  ]
}

Create a session

POST/v1/whatsapp/sessions

Creates a session. It is limited by your plan’s session count, and beyond it the API returns 402 session_limit.

Body
Name	Type	Description
`name`	string	A label for the session, up to 80 characters. Optional.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Sales"
}'

201 Created

{
  "id": "9c1f6a4e-2b7d-4e0a-8f53-6d2a1b7c9e10",
  "name": "Sales",
  "phone": null,
  "status": "created",
  "status_label": "Created",
  "active": false,
  "created_at": "2026-01-15T09:30:00Z"
}

Get a session

GET/v1/whatsapp/sessions/{sessionId}

Returns the session with its current status.

Parameters
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.

curl "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID" \
  -H "X-API-Key: $TUSK_WA_KEY"

200 OK

{
  "id": "9c1f6a4e-2b7d-4e0a-8f53-6d2a1b7c9e10",
  "name": "Sales",
  "phone": "254700000001",
  "status": "ready",
  "status_label": "Ready",
  "active": true,
  "created_at": "2026-01-15T09:30:00Z"
}

Delete a session

DELETE/v1/whatsapp/sessions/{sessionId}

Deletes the session and frees a slot on your plan.

Parameters
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.

curl -X DELETE "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID" \
  -H "X-API-Key: $TUSK_WA_KEY"

200 OK

{
  "deleted": true
}

Start a session

POST/v1/whatsapp/sessions/{sessionId}/start

Starts the session. Returns the session object.

Parameters
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/start" \
  -H "X-API-Key: $TUSK_WA_KEY"

200 OK

{
  "id": "9c1f6a4e-2b7d-4e0a-8f53-6d2a1b7c9e10",
  "name": "Sales",
  "phone": null,
  "status": "initializing",
  "status_label": "Initializing",
  "active": false,
  "created_at": "2026-01-15T09:30:00Z"
}

Stop a session

POST/v1/whatsapp/sessions/{sessionId}/stop

Stops the session and keeps the linked number. Returns the session object.

Parameters
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/stop" \
  -H "X-API-Key: $TUSK_WA_KEY"

Log out and unlink the number

POST/v1/whatsapp/sessions/{sessionId}/logout

Unlinks the number from the session. You must link a number again to use the session. Returns the session object.

Parameters
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/logout" \
  -H "X-API-Key: $TUSK_WA_KEY"

Force-kill a stuck session

POST/v1/whatsapp/sessions/{sessionId}/force-kill

Terminates a session that is stuck. Start it again afterwards. Returns the session object.

Parameters
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/force-kill" \
  -H "X-API-Key: $TUSK_WA_KEY"

Get the QR code

GET/v1/whatsapp/sessions/{sessionId}/qr

Returns the QR code to scan from WhatsApp, under Linked devices. It is available while the status is qr_ready, and the code refreshes, so fetch it again or watch the session.qr event if it expires.

Parameters
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.

curl "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/qr" \
  -H "X-API-Key: $TUSK_WA_KEY"

200 OK

{
  "qrCode": "2@AbCdEf...",
  "status": "qr_ready"
}

The qrCode value is the data to encode as a QR image with any QR library.

Get a pairing code

POST/v1/whatsapp/sessions/{sessionId}/pairing-code

Returns an 8-character code to link by phone number instead of scanning a QR code. Enter it on the phone in WhatsApp, under Linked devices, then Link with phone number.

Body
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.
`phoneNumber`required	string	The number to link, in international format without a plus.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/pairing-code" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "254700000001"
}'

201 Created

{
  "pairingCode": "ABCD-EFGH",
  "status": "qr_ready"
}