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:
ParameterRequiredDescription
tokenYesValid JWT token for authentication

​
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:
Event TypeDescriptionExample Data
notificationSystem notification{"message": "New comment on your post", "level": "info"}
chat_messageNew chat message{"conversation_id": "conv-123", "sender_id": "user-456", "content": "Hello there!"}
status_updateStatus change{"entity_type": "task", "entity_id": "task-789", "status": "completed"}

​
Commands

Clients can send commands to the server:
Command TypeDescriptionExample Data
subscribeSubscribe to a specific channel{"channel": "conversation:conv-123"}
unsubscribeUnsubscribe from a channel{"channel": "conversation:conv-123"}
pingCheck connection{}

​
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:
Error CodeDescription
invalid_requestThe message format is invalid
unauthorizedAuthentication failed or insufficient permissions
subscription_failedFailed to subscribe to the requested channel
internal_errorServer-side error

​
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