Skip to main content

​
WebSocket Protocol

Magne uses a WebSocket connection for real-time event delivery. All presence updates, messages, typing indicators, and voice states are pushed through this channel.

​
Connection

wss://api.magne.chat/v1/ws?token=YOUR_ACCESS_TOKEN
The access token is passed as a query parameter. The server validates the token and associates the connection with the authenticated user.

​
Connection Lifecycle

  1. Connect — Client opens WSS connection with token
  2. Authenticated — Server validates token, registers the session
  3. Events flow — Server pushes events as JSON frames
  4. Heartbeat — Server tracks connection health
  5. Disconnect — Client closes connection or token expires

​
Message Format

All WebSocket messages are JSON-encoded with a consistent structure: 
{
  "eventType": "message.created",
  "data": {
    "id": "msg-uuid",
    "channelId": "channel-uuid",
    "authorId": "user-uuid",
    "content": "Hello world",
    "createdAt": "2026-03-03T12:00:00Z"
  }
}

​
Multi-Session

Users can have multiple simultaneous WebSocket connections (e.g., desktop + mobile). The server tracks connection count per user and only triggers cleanup (voice disconnect, presence offline) when all connections close.
This prevents false presence flickers during reconnection or when switching devices.

​
Reconnection

If disconnected, clients should implement exponential backoff:
  1. Wait 1 second, reconnect
  2. If failed, wait 2 seconds
  3. If failed, wait 4 seconds
  4. Cap at 30 seconds between attempts
  5. Refresh access token if expired before reconnecting