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.

After you start a session, it sits in a CONNECTING state waiting to authenticate with a WhatsApp account. Pairing is how you complete that authentication. Titan offers two methods: scanning a QR code from the WhatsApp app, or entering an 8-digit code via the phone number pairing flow. Both result in the same CONNECTED state; choose based on what works for your use case.

​
QR code pairing

The QR code flow is the standard WhatsApp multi-device linking experience. Your backend fetches the QR code from Titan and renders it for the user to scan.

​
How it works

1

Start the session

Create and start the session if you haven’t already.
curl -X POST https://api.titanapp.dev/api/sessions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "support", "start": true}'
2

Fetch the QR code

Call GET /api/{session}/pair/qr to retrieve the current QR code data. The response includes a qr string — encode it into a QR image and display it to the user.
curl https://api.titanapp.dev/api/support/pair/qr \
  -H "Authorization: Bearer $API_KEY"
Response:
{
  "qr": "2@ABC123...",
  "event": null
}
Add ?format=image to receive a PNG directly instead of JSON:
curl "https://api.titanapp.dev/api/support/pair/qr?format=image" \
  -H "Authorization: Bearer $API_KEY" \
  --output qr.png
3

Poll for QR refreshes

WhatsApp QR codes rotate every ~20 seconds. Poll the endpoint every few seconds and re-render the image whenever the qr value changes. Continue polling until the session status becomes CONNECTED or DISCONNECTED.
# Poll every 5 seconds
while true; do
  STATUS=$(curl -s https://api.titanapp.dev/api/sessions/support \
    -H "Authorization: Bearer $API_KEY" | jq -r '.status')
  echo "Session status: $STATUS"
  [ "$STATUS" = "CONNECTED" ] && break
  [ "$STATUS" = "DISCONNECTED" ] && break
  sleep 5
done
4

User scans the QR code

On the phone that owns the WhatsApp number, open WhatsApp → Settings → Linked Devices → Link a Device, then scan the QR code.
5

Connection confirmed

On success, the session moves to CONNECTED and Titan fires the session.connected webhook with the linked phone number, push name, business name, platform, and LID.If the QR code expires before the user scans it, the session moves to DISCONNECTED with reason QR_TIMEOUT. Restart the session and try again.
Each QR code is valid for approximately 20 seconds. If your UI shows a stale QR, the scan will fail. Always re-render when the qr value changes.

​
Webhook events during pairing

Subscribe to these events on your webhook to track the pairing flow in real time:
EventWhen it fires
session.qrA new QR code is available (fires each time the code rotates)
session.statusThe session status changes (e.g. CONNECTING → CONNECTED)
session.connectedPairing succeeded; includes phone number, push name, and LID
session.logged_outThe WhatsApp account unlinked the device
The session.connected payload: 
{
  "phoneNumber": "+15551234567",
  "pushName": "Support Bot",
  "businessName": "Acme Corp",
  "platform": "smba",
  "lid": "12345678901234567@lid"
}

​
After pairing

Once the session is CONNECTED, you can start sending and receiving messages immediately. Titan maintains the connection and reconnects automatically after brief interruptions. If the user logs out (session.logged_out), you must re-pair the session.
Store the session name alongside the linked phone number in your own database so you can look up which session to use when sending messages to or from a specific number.