WhatsApp sessions
Create a session, authorize it through Linked devices, inspect connection state, and manage its lifecycle.
Create a session#
Use an account-wide key with manage permission. Session creation is asynchronous and consumes one slot from your plan allowance.
nameRequired- string · 2–80 characters
A name for this connection in your workspace.
curl --request POST 'https://turbinewhats.app/api/v1/channels' \
--header "Authorization: Bearer $TURBINEWHATS_TOKEN" \
--header 'Content-Type: application/json' \
--data '{"name":"Order notifications"}'{
"data": {
"id": "1d848fa6-b0c2-4d28-b870-09f44d750d93",
"state": "queued"
}
}Authorize the connection#
Refresh GET /channels/{id}/status with read permission until preparation completes. Retrieve GET /channels/{id}/qr with manage permission when a QR code is available.
The QR response contains data.qrCode as an image data URL and data.status from the gateway. Display it privately to the account owner. Use WhatsApp → Linked devices → Link a device to scan it. Refresh when the QR expires.
Do not send until status reports ready. The status response contains id, state, and phone. The pairing response contains qrCode and status.
curl 'https://turbinewhats.app/api/v1/channels/1d848fa6-b0c2-4d28-b870-09f44d750d93/status' \
--header "Authorization: Bearer $TURBINEWHATS_TOKEN"{
"data": {
"id": "1d848fa6-b0c2-4d28-b870-09f44d750d93",
"state": "ready",
"phone": "14155550123"
}
}Connection states#
| State | Meaning |
|---|---|
| queued / created | Provisioning is queued or the gateway session exists. |
| initializing / authenticating | The gateway is starting or WhatsApp authorization is in progress. |
| qr_ready | The account owner needs to scan the current QR code. |
| ready | The connection can accept new sends, subject to account and plan limits. |
| disconnected / stopped | The connection is unavailable or has been stopped. Use start when appropriate. |
| needs_attention / failed / action_required | Preparation or the connection requires investigation. Check status or contact support. |
| trial_restricted | The connected number is not eligible for another account’s trial. |
| expired | Access has expired and the connection has been stopped. |
| stopping / deleting / deleted | A lifecycle operation is queued or completed. |
Start, stop, or remove#
All three operations require manage. Stop and delete remain available after plan expiry. Removing a session does not cancel subscription renewal; manage billing separately in the workspace. A deleted connection may need a new session and QR authorization to reconnect.
| Operation | Behavior |
|---|---|
| POST /channels/{id}/start | Start an existing connection. The response reports initializing; check status afterward. |
| POST /channels/{id}/stop | Queue a stop operation. The response contains data.queued=true. |
| POST /channels/{id}/delete | Queue logout and deletion. The response contains data.queued=true. |