Sessions and statuses | Tusk WhatsApp API

What does a session look like?

Session object

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

Name	Type	Description
`id`	string	The session id. Use it as `sessionId` in paths.
`name`	string	The label you gave the session, up to 80 characters.
`phone`	string \| null	The linked number, or null until a number is linked.
`status`	string	Machine-readable status. See the table below.
`status_label`	string	Human-readable status for display.
`active`	boolean	Whether the session is currently connected and usable.
`created_at`	string	ISO 8601 creation time in UTC.

Which statuses can a session have?

status	Meaning
`created`	The session exists but has not been started.
`initializing`	The session is starting up.
`qr_ready`	A QR code is available. Scan it, or request a pairing code instead.
`authenticating`	The number is being linked.
`ready`	Linked and connected. You can send and receive messages.
`disconnected`	The connection dropped. Start the session again.
`action_required`	The session needs attention before it can be used. Check the dashboard, and if it does not clear, log out and link the number again.
`failed`	The session could not start. Try force-kill and start again, and if it keeps failing, log out and link the number again.

Send messages only while the status is ready. Subscribe to the session.status webhook event to react to changes without polling.

How do I link a number?

After POST /sessions/{sessionId}/start, the session reaches qr_ready. Link it in one of two ways:

QR code. GET /sessions/{sessionId}/qr returns the code to scan from WhatsApp, under Linked devices.
Pairing code. POST /sessions/{sessionId}/pairing-code with the phone number returns an 8-character code you enter on the phone, under Linked devices, then Link with phone number. Handy when you cannot scan a screen.

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"
}'

How do I manage a session over time?

start: Starts a stopped or new session. A previously linked number reconnects without a new QR code.
stop: Disconnects the session but keeps the linked number.
logout: Unlinks the number. You need to link again to use the session.
force-kill: Terminates a stuck session. Start it again afterwards.
DELETE: Deletes the session and frees a slot on your plan.

The number of sessions you can create depends on your plan. See plan and limits.