◴ Status Tracker API

REST API for managing WhatsApp sessions, sending statuses, and reading viewer analytics. Version 2.0.0.

Compliance: this tool drives WhatsApp through Baileys (an unofficial Web client), not the official Cloud API. Automated status posting and viewer tracking can violate WhatsApp's Terms of Service and may get a number banned. Use a number you control, at human pace, and do not bulk-message strangers.

Authentication

Every /api request must include your API key, set as API_KEY in the server's .env.

x-api-key: YOUR_API_KEY
# or
Authorization: Bearer YOUR_API_KEY

Requests are rate-limited per IP (default 300 requests / 15 min). Responses are JSON: { "success": true, "data": ... } or { "success": false, "error": "..." }.

Sessions

POST/api/sessions

Create and start a session.

Field	Required	Notes
sessionId	yes	letters, numbers, `_`, `-` (≤64)
sessionName	yes	display name
authMethod	no	`pairing` (default) or `qrcode`
phoneNumber	if pairing	10–15 digits incl. country code

curl -X POST http://localhost:3000/api/sessions \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
  -d '{"sessionId":"acc1","sessionName":"My Account","authMethod":"pairing","phoneNumber":"919812345678"}'

GET/api/sessions

List all sessions with connection state.

DELETE/api/sessions/:sessionId

Delete a session, its auth, statuses and viewers.

POST/api/sessions/:sessionId/restart

Tear down and reconnect a session.

PUT/api/sessions/:sessionId/phone-number

Update the pairing phone number. Body: { "phoneNumber": "..." }

Authentication state

GET/api/sessions/:sessionId/connection-status

Returns connected, authMethod, current pairingCode/qrCode (data URL), phoneNumber, ownNumber.

GET/api/sessions/:sessionId/pairing-code

POST/api/sessions/:sessionId/request-pairing-code

Read or request a fresh 8-digit pairing code (only valid before the session is connected).

Statuses

POST/api/sessions/:sessionId/send-status

Field	Notes
type	`text` \| `image` \| `video` \| `url`
content	text body, uploaded filename, or media URL
caption	optional (media only)
targetNumbers	optional, comma-separated; empty = your own number

# text
curl -X POST .../sessions/acc1/send-status \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
  -d '{"type":"text","content":"Hello from the API"}'

# image (upload first, then send the returned filename)
curl -X POST .../upload-image -H "x-api-key: $KEY" -F "image=@./pic.jpg"
# -> { "data": { "filename": "1730000000-ab12.jpg" } }
curl -X POST .../sessions/acc1/send-status \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
  -d '{"type":"image","content":"1730000000-ab12.jpg","caption":"hi"}'

GET/api/sessions/:sessionId/sent-statuses

List statuses from the last 24 hours.

GET/api/sessions/:sessionId/status-viewers/:statusId

List who has viewed a status, with timestamps.

DELETE/api/sessions/:sessionId/delete-status/:statusId

WhatsApp does not allow deleting a published status via API. This removes only local tracking data; the status remains on recipients' phones until the natural 24-hour expiry.

Media uploads

POST/api/upload-image

POST/api/upload-video

Multipart form upload (field image or video). Returns a stored filename to pass as content. Max size set by MAX_UPLOAD_MB.

System

GET/api/health

GET/api/stats

GET/api/storage

Health check, aggregate stats, and per-session DB storage usage.

WebSocket events

Connect via Socket.IO at the server root. Events emitted:

connection-status      { sessionId, connected, ownNumber?, status? }
pairing-code           { sessionId, pairingCode, phoneNumber }
qr-code                { sessionId, qrCode }
status-sent            { sessionId, id, type, ... }
status-viewers-update  { sessionId, statusId, viewers[] }
status-deleted         { sessionId, statusId }
statuses-updated       { sessionId }
session-created        { sessionId, ... }
session-deleted        { sessionId }