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; a public event-stream API for third-party clients is not yet documented in the OpenAPI spec (v0.23.1). The notes in this guide are about operating the channel correctly, not about consuming events from it.

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	Not documented for external clients	Per-webhook event filters
Delivery guarantees	Not documented for external clients	Retry with backoff, delivery-failure log
Public API	Not yet documented	Full reference in the API reference

If you need events in your own code, start with webhooks. Revisit WebSocket once a public event-stream API is released.

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.

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: websocket handling is automatic for routes.
• Traefik: a normal HTTP router forwards WebSocket upgrades automatically.
• Nginx: set Upgrade and Connection headers 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

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.