The dashboard and any Socket.io client can receive live QR codes, session status, inbox messages, campaign progress, and in-app notifications without polling REST.

Connect to `https://api.actiwapi.com` with the same JWT you use for REST. After connect, join a session room to receive QR and per-session message events.

Connect with JWT

Use the official socket.io-client. Pass the access token in handshake.auth.token (query.token is also accepted). Invalid or expired tokens close the handshake with “Invalid or expired token”.

URL: https://api.actiwapi.com (same host as the REST API, not /api).
transports: websocket first, polling fallback.
On success the server emits connected with { userId, tenantId, events }.
The socket automatically joins tenant:{tenantId} and user:{userId}.

Server events

These names are canonical. Payloads always include a timestamp when the server emits them.

qr_generated — { sessionId, qr } while pairing. Render the QR in your UI.
session_connected / session_disconnected / session_status_update — connection lifecycle.
message_received / message_sent — inbox and outbound pipeline.
campaign_started / campaign_completed — bulk send lifecycle.
notification_new — in-app notification for the user or whole tenant.

Webhooks are the right choice for backend automation. Socket.io is for interactive UIs. Do not put the JWT in a public browser app that untrusted users can inspect.

Minimal client

Install socket.io-client, connect with your JWT, subscribe to the session you are pairing, then listen for qr_generated.

io(SOCKET_URL, { auth: { token: accessToken } })
socket.on("connected", handler)
socket.emit("subscribe:session", sessionId)
socket.on("qr_generated", ({ qr }) => { /* render QR image */ })

Error codes

Failed requests return a JSON envelope with success: false and a human-readable message.

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "phone": "Valid phone number is required"
  }
}

HTTP	Code	Description
400	VALIDATION_ERROR	Request body or query failed validation.
401	UNAUTHORIZED	Missing or invalid JWT / API key.
403	FORBIDDEN	Authenticated but lacking permission or entitlement.
403	SUBSCRIPTION_INACTIVE	Action not allowed on the current plan (including Free after trial). Upgrade or wait for entitlements.
403	LIMIT_EXCEEDED	Plan limit reached (sessions, messages, API requests, etc.).
404	NOT_FOUND	Resource does not exist or is not in your account.
409	CONFLICT	Duplicate resource or invalid state transition.
429	RATE_LIMITED	Too many requests; retry after backoff.
500	INTERNAL_ERROR	Unexpected server error.
502	WHATSAPP_UNAVAILABLE	WhatsApp session disconnected or provider error.

Connect with JWT

Subscribe to a session

Server events

Minimal client

Error codes