API reference for real-time communication using WebSockets
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.
WebSocket connections require authentication via a valid JWT token provided as a query parameter.
Create a persistent WebSocket connection.
When using HTTPS, use the wss://
protocol instead:
Query Parameters:
Parameter | Required | Description |
---|---|---|
token | Yes | Valid JWT token for authentication |
Messages exchanged over the WebSocket connection are JSON-formatted with the following structure:
The WebSocket service broadcasts various events to connected clients:
Event Type | Description | Example Data |
---|---|---|
notification | System notification | {"message": "New comment on your post", "level": "info"} |
chat_message | New chat message | {"conversation_id": "conv-123", "sender_id": "user-456", "content": "Hello there!"} |
status_update | Status change | {"entity_type": "task", "entity_id": "task-789", "status": "completed"} |
Clients can send commands to the server:
Command Type | Description | Example Data |
---|---|---|
subscribe | Subscribe to a specific channel | {"channel": "conversation:conv-123"} |
unsubscribe | Unsubscribe from a channel | {"channel": "conversation:conv-123"} |
ping | Check connection | {} |
The server may send error messages in the following format:
Common error codes:
Error Code | Description |
---|---|
invalid_request | The message format is invalid |
unauthorized | Authentication failed or insufficient permissions |
subscription_failed | Failed to subscribe to the requested channel |
internal_error | Server-side error |
It’s recommended to implement a reconnection strategy in your client application to handle unexpected disconnections:
API reference for real-time communication using WebSockets
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.
WebSocket connections require authentication via a valid JWT token provided as a query parameter.
Create a persistent WebSocket connection.
When using HTTPS, use the wss://
protocol instead:
Query Parameters:
Parameter | Required | Description |
---|---|---|
token | Yes | Valid JWT token for authentication |
Messages exchanged over the WebSocket connection are JSON-formatted with the following structure:
The WebSocket service broadcasts various events to connected clients:
Event Type | Description | Example Data |
---|---|---|
notification | System notification | {"message": "New comment on your post", "level": "info"} |
chat_message | New chat message | {"conversation_id": "conv-123", "sender_id": "user-456", "content": "Hello there!"} |
status_update | Status change | {"entity_type": "task", "entity_id": "task-789", "status": "completed"} |
Clients can send commands to the server:
Command Type | Description | Example Data |
---|---|---|
subscribe | Subscribe to a specific channel | {"channel": "conversation:conv-123"} |
unsubscribe | Unsubscribe from a channel | {"channel": "conversation:conv-123"} |
ping | Check connection | {} |
The server may send error messages in the following format:
Common error codes:
Error Code | Description |
---|---|
invalid_request | The message format is invalid |
unauthorized | Authentication failed or insufficient permissions |
subscription_failed | Failed to subscribe to the requested channel |
internal_error | Server-side error |
It’s recommended to implement a reconnection strategy in your client application to handle unexpected disconnections: