Connect to the real-time Socket.IO channel
OpenWA runs a real-time Socket.IO channel on the same port as the REST API, dashboard, and Swagger (default 2785). The built-in dashboard uses it to show session status and incoming activity the moment it happens. This guide explains where the channel lives, how it behaves behind proxies and tunnels, and how to troubleshoot a connection that will not establish.
For receiving events in your own application, use webhooks, they are the supported, documented integration point. The Socket.IO channel currently serves the dashboard; Socket.IO is a separate protocol and is not represented in the REST OpenAPI spec. The protocol below describes the channel in v0.31.0; it has no durable replay or retry guarantee.
When to use WebSocket vs webhooks
| WebSocket (Socket.IO) | Webhooks | |
|---|---|---|
| Direction | Bidirectional, long-lived connection | One-way HTTP push |
| Client | Dashboard (built-in) | Your server endpoint |
| Event filtering | Per-session/event subscriptions, chat scope | Per-webhook event filters |
| Delivery guarantees | Live connection only; no durable replay | Retry with backoff, delivery-failure log |
| API shape | Socket.IO message frames | Full reference in the API reference |
If you need events in your own code, start with webhooks. Use Socket.IO when live updates are enough and your client can reconnect and resubscribe.
Where the channel lives
The channel is served from the /socket.io/ path on the same port as everything else — there is no separate WebSocket port.
http://localhost:2785/socket.io/
In production, the same URL is served through your domain over TLS. Because the REST API, dashboard, Swagger, and Socket.IO share one port, any proxy in front of OpenWA must forward WebSocket upgrades and allow long-lived connections.
/socket.io/ is the transport path your proxy forwards, not the address a client connects to. The gateway serves a single namespace, /events, so a client targets io("http://localhost:2785/events", { auth: { apiKey } }). Since v0.26.0 a client that connects to the root namespace / is refused with an Invalid namespace error, and a client that joins no namespace is closed by Socket.IO's connect timeout (45 seconds by default). Before, the bare origin landed on Socket.IO's default namespace, which carries no events but accepted any client without a key and kept it connected outside the handshake and per-key socket limits.
Subscribe to events
import { io } from "socket.io-client";
const socket = io("http://localhost:2785/events", {
auth: { apiKey: "YOUR_API_KEY" },
});
socket.on("message", (frame) => {
if (frame.type === "event") {
console.log(frame.payload.event, frame.payload.sessionId, frame.payload.data);
} else {
console.log(frame); // subscribed, unsubscribed, pong or error
}
});
socket.on("connect", () => {
socket.emit("message", {
type: "subscribe",
sessionId: "8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a",
events: ["message.received", "message.ack", "event.response"],
requestId: "subscribe-1",
});
});
Send every command on message: { type: "subscribe", sessionId, events, requestId? }, { type: "unsubscribe", sessionId, requestId? } or { type: "ping", requestId? }. Replies are flat objects with type, an ISO timestamp, and the echoed requestId; pushed events are { type: "event", timestamp, payload: { event, sessionId, data } }. In v0.26.0 only a string requestId of at most 128 characters is echoed; all other values are dropped. Subscribe and unsubscribe require sessionId: "*" or an ID of at most 128 letters, digits and hyphens. Since v0.26.0 the server closes a connection that sends a client frame over 8 KiB, without answering it (the Socket.IO default was 1 MB); a legal subscribe frame is a small fraction of that, and a polling request body over the limit is answered 413.
Use events: ["*"] for all permitted events except message.receipt, which a subscription receives only when it names it (v0.26.0+). Exact names are message.received, message.sent, message.ack, message.receipt, message.revoked, message.reaction, message.edited, session.status, session.qr, session.authenticated, session.disconnected, session.restriction, group.join, group.leave, group.update, group.join_request, call.received, call.accepted, call.rejected, call.missed, status.received, presence.update, event.response and poll.vote. message.failed and session.reconnect_loop are webhook-only. Unknown names mixed with valid ones are dropped; an array without a recognized name returns INVALID_EVENTS. On session events, payload.data differs slightly from the webhook data object: session.status, session.authenticated, session.disconnected, and session.restriction omit the redundant sessionId inside data (since payload.sessionId already carries it), and session.qr carries { qrCode } where the webhook carries { qr }. The message.received, message.sent (including isForwarded: true and forwardingScore on forwarded messages since v0.29.1), message.receipt, and poll.vote socket events carry the same data as their webhooks; RSVP, poll vote and receipt payloads and engine limitations are in Webhooks, Poll vote payloads and Receipt payloads. The webhook-side bound on receipts does not apply to the socket.
An unrestricted key may subscribe to sessionId: "*" or any [A-Za-z0-9-]{1,128} session id (the subscribe handler checks only the id format, not whether a session row with that id exists). A key with allowedSessions must name one allowed session; otherwise it gets FORBIDDEN_SESSION. Viewer keys never receive session.qr, even through a wildcard. Each subscribe revalidates the key. Since v0.26.0, a subscribe that is still revalidating when an unsubscribe for the same session (or "*") is answered joins no rooms and returns SUBSCRIPTION_CANCELLED. A valid connection is live only: after reconnect, subscribe again and reconcile missed data through REST or webhooks.
With REDIS_ENABLED=true, events raised on another replica reach the client through a Redis pub/sub adapter. That fan-out is best effort and keeps no replay queue. Since v0.26.0 the publishing connection is dropped when Redis stays silent for 10 seconds, and the events a node raises while it is disconnected, plus its reconnect backoff of up to 5 seconds, are dropped for clients on other replicas instead of being delivered late (before, the node held every event in memory for as long as Redis stayed silent). A Redis that answers but slowly is held to about 12,000 unanswered events, and further events are dropped for the other replicas until it catches up. The subscribing connection is pinged every 15 seconds and replaced after 30 seconds without an answer, so a connection that a proxy keeps open after Redis stopped answering costs a node the other replicas' events for about 45 seconds at most. Clients on the replica that raised the event are served directly and are not affected; webhooks do not use this path. QUEUE_PREFIX (v0.26.0+) covers the BullMQ queues only, not this fan-out, so deployments that share one Redis with REDIS_ENABLED=true also share each other's socket events and need a Redis each. See Scaling.
Chat-restricted subscriptions (v0.25.0+)
Keys with allowedChats can connect and receive only allowed chat events: the seven message events above (message.receipt included, v0.26.0+), group.join, group.leave, group.update, presence.update, event.response and poll.vote (v0.26.0+). Message, presence, RSVP and poll vote events need a resolvable data.chatId; group events need data.groupId. Persisted phone/LID aliases are checked at delivery time (with a 5-second cache per session and allowlist since v0.28.0), including mappings learned after subscribe. An event without a resolvable chat is omitted, including across Redis replicas.
Account events, calls, statuses, QR codes and group.join_request are omitted, even with events: ["*"]. A request containing only disallowed events returns FORBIDDEN_EVENTS. The key can hold at most 2000 allowlist entries, and each socket at most 4096 subscription rooms. For chat-restricted keys, literal address forms multiply the cost of each session/event subscription. If a frame alone exceeds the cap, request fewer event names or use "*"; unsubscribe first when existing rooms cause the overflow. Older stored allowlists whose address forms alone exceed 4096 must be shortened. The error is TOO_MANY_SUBSCRIPTIONS.
Proxy requirements
A plain HTTP reverse proxy that does not understand WebSocket upgrades will forward the initial request but drop the upgrade, leaving the dashboard stuck on "Connecting…". Configure your proxy to forward upgrades:
- Caddy:
websockethandling is automatic for routes. - Traefik: a normal HTTP router forwards WebSocket upgrades automatically.
- Nginx: set
UpgradeandConnectionheaders explicitly on the/socket.io/location. - Cloudflare Tunnel: forwards WebSocket upgrades natively — no special configuration. See Expose OpenWA with a Cloudflare Tunnel.
Two operational cautions when adding a proxy hop:
- Long-lived connections and timeouts: an idle-timeout that closes the connection will silently drop the dashboard's live view. Set generous read/idle timeouts for the
/socket.io/route. - Double hops: each extra hop between the client and OpenWA adds a connection that can die independently. If the dashboard connects but status goes stale, remove extra proxy layers before investigating OpenWA itself.
Engine note: Baileys is a WebSocket client
On the baileys engine (ENGINE_TYPE=baileys), OpenWA itself is a WebSocket client to WhatsApp — it needs no browser. This is separate from the Socket.IO channel OpenWA serves. If you proxy outbound traffic, remember that the engine's WhatsApp WebSocket and media transfers are outbound connections, not the inbound /socket.io/ channel. See Sessions for engine trade-offs.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Dashboard loads but status stays "Connecting…" | WebSocket upgrade blocked by a proxy, tunnel, or WAF rule | Verify the proxy forwards upgrades; remove extra hops; check Cloudflare WAF rules |
| Status goes stale after a while | Idle-timeout closed the long-lived connection | Raise read/idle timeouts on the /socket.io/ route |
| Works locally, fails behind the tunnel | TLS or WAF terminating the upgrade | Use a Cloudflare Tunnel (forwards upgrades natively) and confirm the tunnel is healthy |
| Reconnects in a loop behind a load balancer | Multiple instances or double hop exhausting long-lived connections | Point the channel at a single upstream; see Scaling |
Disconnected right after connecting, with an UNAUTHORIZED or INTERNAL_ERROR error frame | The key is missing or fails validation (UNAUTHORIZED), or the key store could not be read during the handshake (INTERNAL_ERROR, v0.27.0+; earlier releases answered UNAUTHORIZED). Before v0.25.0 chat-restricted keys were also refused | Connect with a valid key (or retry after INTERNAL_ERROR); for chat-restricted subscriptions use v0.25.0 or later; see Authentication |
A connected client is dropped with an UNAUTHORIZED frame after its key changed | Authorization changes evict local sockets immediately; a minute sweep also catches direct database changes, expiry and a connection racing a change, and a subscribe whose key revalidation finds the key invalid closes the connection as well (if the key store cannot be read during subscribe, the gateway answers INTERNAL_ERROR and leaves the socket open so the client can retry, v0.27.0+). A changed chat authorization is checked on the next subscribe too. Each node has its own auth database, so a change on another node must be repeated locally | Reconnect with a valid key and resubscribe. Renaming a key disconnects nobody |
Refused with RATE_LIMITED: too many connection attempts | More failed or refused handshakes from one client address than the window allows (10 per 60 s by default). Since v0.23.6 an IPv6 client counts against its whole /64, so clients sharing one IPv6 network share the window | Fix the key the failing client sends; where several clients share one IPv6 network, raise WS_RATE_LIMIT_HANDSHAKE_MAX (see Configuration and Authentication) |
Refused with RATE_LIMITED: too many concurrent connections for the key | The key already holds its cap of simultaneous sockets (WS_MAX_SOCKETS_PER_KEY, default 16). Before v0.23.6 a handshake whose transport closed while the key was being validated, which a flaky proxy hop can cause, kept its slot until OpenWA restarted or the key's sockets were closed by a revoke, deletion, expiry or authorization change | Close idle dashboard tabs or raise the cap; on an older release, restart OpenWA to release the stuck slots |
Connection refused with Invalid namespace, or closed after about 45 seconds with no events | The client connected to the root namespace / (v0.26.0+) instead of /events | Connect to /events, as in the example above |
Connection closed with no reply right after a large subscribe | The frame was over 8 KiB (v0.26.0+) | Send only subscribe, unsubscribe and ping frames; none needs more than a small fraction of the limit |
A subscribe, unsubscribe or ping reply arrives twice | Since v0.23.6 the gateway sends each command reply that leaves the socket open (the confirmation, the pong, and refusals such as FORBIDDEN_SESSION) on the message event as well as through the emit's ack callback (a frame-rate RATE_LIMITED refusal already went both ways before), so a client that passes an ack and also listens on message receives it on both. A subscribe refused with UNAUTHORIZED closes the socket, and that refusal arrives only on message | Handle replies in one place: emit without an ack callback and read every reply on message. If you keep the ack, still handle UNAUTHORIZED frames in the message listener: a refusal that closes the socket, and every eviction, arrives only there |
No subscribe confirmation, pong or FORBIDDEN_SESSION refusal ever arrives (before v0.23.6) | Earlier releases returned command replies only through the ack callback, so a client that emitted without one saw no confirmation, no pong, and none of the FORBIDDEN_SESSION, INVALID_SESSION, INVALID_EVENTS or INVALID_MESSAGE refusals | Pass an ack callback when emitting, or upgrade to v0.23.6 |
Next steps
- Receive events in your application with Webhooks.
- Serve the channel over HTTPS without opening inbound ports — Cloudflare Tunnel.
- Understand connection state with Sessions.