Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usetitan.app/llms.txt

Use this file to discover all available pages before exploring further.

A session represents a single WhatsApp account connected to Titan. Every message you send or receive flows through a session, and every session has a name you choose — like support, sales, or user-42 — that you use to identify it across all API calls. Before a session can send or receive messages, you must start it and complete pairing so it authenticates with WhatsApp.

​
Session lifecycle

A session moves through a predictable series of states from creation to active use: 
Create → Start → Pair (QR or phone) → CONNECTED → [send & receive] → Stop / Delete
After pairing succeeds, Titan automatically reconnects the session whenever it drops — you don’t need to re-pair.

​
Session statuses

Every session has a status and an optional statusReason. Poll GET /api/sessions/{session} or subscribe to the session.status webhook to track state changes.
StatusReasonWhat it means
CONNECTINGSCAN_QRWaiting for the user to scan the QR code
CONNECTINGAUTO_RECONNECTTemporarily disconnected; reconnecting automatically
CONNECTED—Authenticated and ready to send and receive messages
DISCONNECTEDMANUAL_STOPStopped via the API
DISCONNECTEDQR_TIMEOUTQR code expired before it was scanned
DISCONNECTEDLOGGED_OUTThe WhatsApp account unlinked this device
DISCONNECTEDFAILEDConnection error
DISCONNECTEDTEMPORARY_BANTemporary suspension by WhatsApp
DISCONNECTEDSTREAM_ERRORWebSocket stream error
AUTO_RECONNECT is normal and expected after transient network issues. Titan handles reconnection for you; your application does not need to restart the session.

​
Session naming rules

Session names must match the pattern ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$. In plain terms:
  • Start with a letter or digit
  • May contain letters, digits, dots (.), hyphens (-), and underscores (_)
  • Between 1 and 64 characters total
Valid examples: default, support-team, user.42, prod_bot_1

​
Operations

​
Create a session

curl -X POST https://api.titanapp.dev/api/sessions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "support"}'
Pass "start": true to create and start the session in a single request. Without it, the session is created in a stopped state and you must call the start endpoint separately.

​
List sessions

curl https://api.titanapp.dev/api/sessions \
  -H "Authorization: Bearer $API_KEY"
Returns an array of all sessions for your account, each with its current status and statusReason.

​
Start a session

curl -X POST https://api.titanapp.dev/api/sessions/support/start \
  -H "Authorization: Bearer $API_KEY"
Starting a session moves it to CONNECTING with reason SCAN_QR (or AUTO_RECONNECT if credentials already exist). You then need to pair it — see Pairing.

​
Stop a session

curl -X POST https://api.titanapp.dev/api/sessions/support/stop \
  -H "Authorization: Bearer $API_KEY"
Sets the session to DISCONNECTED with reason MANUAL_STOP. The session and its credentials are preserved; call start again to reconnect.

​
Restart a session

curl -X POST https://api.titanapp.dev/api/sessions/support/restart \
  -H "Authorization: Bearer $API_KEY"
Equivalent to stop followed by start. Useful for clearing transient errors.

​
Get session details

curl https://api.titanapp.dev/api/sessions/support \
  -H "Authorization: Bearer $API_KEY"
Returns the full session object including the connected phone number, push name, business name, platform, and Linked Device ID (LID) once the session is CONNECTED.

​
Delete a session

curl -X DELETE https://api.titanapp.dev/api/sessions/support \
  -H "Authorization: Bearer $API_KEY"
Permanently removes the session and its credentials. To reconnect the same WhatsApp number, you must create a new session and pair again.

​
Auto-reconnect

When a connected session loses its connection due to a network issue or brief outage, Titan automatically attempts to reconnect it. The session transitions to CONNECTING with reason AUTO_RECONNECT and returns to CONNECTED once the connection is restored. You receive session.status webhook events for each transition.
You do not need to watch for AUTO_RECONNECT and restart sessions yourself. Only act on DISCONNECTED status with reasons like LOGGED_OUT, FAILED, or TEMPORARY_BAN — those require human or programmatic intervention.

​
Per-session proxy

Each session can route its WhatsApp traffic through its own HTTP or HTTPS proxy. Pass the proxy URL in the config object when creating or updating a session: 
curl -X POST https://api.titanapp.dev/api/sessions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support",
    "start": true,
    "config": {
      "proxy": "http://user:[email protected]:8080"
    }
  }'

​
Session adoption

If you have existing WhatsApp sessions from Baileys or whatsapp-web.js, you can import their credentials into Titan without re-pairing. Contact support for migration assistance.