WebSocket Service API

The WebSocket Service provides endpoints for establishing persistent connections between clients and the server, enabling real-time, bidirectional communication. This service is used for features that require instant updates and notifications.

​

Authentication

WebSocket connections require authentication via a valid JWT token provided as a query parameter.

​

Base URL

/api/ws

​

WebSocket Endpoints

​

Establish Connection

Create a persistent WebSocket connection.

ws://your-api-domain.com/api/ws?token=YOUR_JWT_TOKEN

When using HTTPS, use the wss:// protocol instead:

wss://your-api-domain.com/api/ws?token=YOUR_JWT_TOKEN

Query Parameters:

​

Message Format

Messages exchanged over the WebSocket connection are JSON-formatted with the following structure:

​

Client-to-Server Messages

{
  "type": "message_type",
  "data": {
    // Message-specific payload
  }
}

​

Server-to-Client Messages

{
  "type": "message_type",
  "data": {
    // Message-specific payload
  },
  "timestamp": "2023-08-15T10:30:00Z"
}

​

Message Types

​

Events

The WebSocket service broadcasts various events to connected clients:

​

Commands

Clients can send commands to the server:

​

Error Handling

The server may send error messages in the following format:

{
  "type": "error",
  "data": {
    "code": "invalid_request",
    "message": "Invalid message format"
  },
  "timestamp": "2023-08-15T10:31:00Z"
}

Common error codes:

​

Connection Example

​

JavaScript Client Example

// Establish WebSocket connection
const token = "your-jwt-token";
const socket = new WebSocket(`wss://your-api-domain.com/api/ws?token=${token}`);

// Connection opened
socket.addEventListener('open', (event) => {
  console.log('Connected to WebSocket server');
  
  // Subscribe to a channel
  socket.send(JSON.stringify({
    type: 'subscribe',
    data: {
      channel: 'conversation:conv-123'
    }
  }));
});

// Listen for messages
socket.addEventListener('message', (event) => {
  const message = JSON.parse(event.data);
  console.log('Message from server:', message);
  
  // Handle different message types
  switch (message.type) {
    case 'chat_message':
      // Handle new chat message
      break;
    case 'notification':
      // Handle notification
      break;
    case 'error':
      // Handle error
      break;
  }
});

// Connection closed
socket.addEventListener('close', (event) => {
  console.log('Disconnected from WebSocket server:', event.code, event.reason);
});

// Send a message
function sendMessage(content) {
  socket.send(JSON.stringify({
    type: 'chat_message',
    data: {
      conversation_id: 'conv-123',
      content: content
    }
  }));
}

​

Reconnection Strategy

It’s recommended to implement a reconnection strategy in your client application to handle unexpected disconnections:

1. Start with a small delay (e.g., 1 second)
2. Use exponential backoff with jitter to increase the delay between reconnection attempts
3. Set a maximum retry limit or maximum delay
4. Reset the delay when a successful connection is established

​

Security Considerations

• WebSocket connections are authenticated using JWT tokens
• Tokens should be kept secret and not shared
• Connections will be terminated when tokens expire
• The server may implement rate limiting to prevent abuse

​

Implementation Notes

• The WebSocket service uses the standard WebSocket protocol (RFC 6455)
• Messages are exchanged in JSON format
• The service supports multiple concurrent connections
• Channel subscriptions allow for efficient message filtering
• Clients should handle reconnection logic on their side