Realtime WebSocket Events

Realtime WebSocket Events

One WebSocket carries the events a client needs while online: presence changes from friends, game invites, and match results. Connect to GET /v1/ws with the API key and the session token. A realtime Hub holds the connection and pushes events as they happen.

Event types

The main events are presence updates, invite notifications, and matchmaker_matched when a match forms. Each event names its type, so the client can route it without guessing.

Recovery by polling

The WebSocket speeds delivery up, and every event also has a REST fallback. A missed matchmaker_matched is recoverable with GET /v1/matchmaker/tickets/{id}, and pending invites are readable with GET /v1/invite. Reconnect, poll once, and the client is caught up.

Connecting

Pass the session token when you open the socket. Most WebSocket clients send it as a header:

GET /v1/ws
Authorization: Bearer <api_key>
X-Session-Token: <access_token>

Full reference: the /v1/ws operation, plus the matchmaker and invite endpoints for the polling fallbacks.