Pairing a number

An app sends nothing until a WhatsApp account is linked. There are two ways.

QR code

curl -s http://localhost:3000/api/qr -H "x-api-key: $APP_KEY"

Response	Meaning
200 { "status": "qr", "qr": "data:image/png;base64,..." }	Show this image and scan it.
202 { "qr": null }	Not ready yet. Retry in a few seconds.
200 { "status": "ready", "qr": null }	Already connected.

On the phone: WhatsApp, Linked devices, Link a device. QR codes rotate, so keep polling and refresh the image until status is ready.

Phone-number pairing code

curl -s -X POST http://localhost:3000/api/pairing-code \
  -H "x-api-key: $APP_KEY" -H "Content-Type: application/json" \
  -d '{"phoneNumber":"15551234567"}'
# {"pairingCode":"ABCDEFGH","expiresIn":180}

Enter the code in Linked devices, Link with phone number. Cancel with DELETE /api/pairing-code to return to QR mode.

Unlinking

POST /api/logout logs the account out and wipes the stored session. The app keeps its key, webhook and message history and shows a fresh QR code.

Inactive sessions

A session is re-saved only while its app is connected. After SESSION_INACTIVE_DAYS (default 7) offline, the hourly cleanup deletes the stored login and the app needs a new scan. See Configuration.