WebSocket API

The WebSocket endpoint provides real-time, bidirectional communication for chat. It supports both synchronous (full message) and streaming (incremental chunks) reply modes.

Endpoint

WebSocket WS /ws

Authentication: Send a valid JWT in the Authorization header during the WebSocket handshake. If authentication fails, the connection is closed with code 4001. Internal errors may close with code 4000.

Message format

All messages must be JSON and follow this structure:

{
  "conversation_id": "string",
  "type": "string",
  "message_id": "string (optional)",
  "data": {}
}

Event: new_message_request

Requests a synchronous (non-streaming) reply: the server processes the message and sends back one complete response.

Request:

{
  "conversation_id": "string",
  "type": "new_message_request",
  "data": {
    "content": "user message text",
    "type": "human"
  }
}

Response:

{
  "conversation_id": "string",
  "type": "new_message_response",
  "data": {
    "content": "full AI reply",
    "type": "ai"
  }
}

Flow: The server validates data as a human message, loads or creates the conversation in Redis, runs the conversation pipeline, updates cache, saves to the database, and sends the single response above.

Event: new_message_stream_request

Requests a streaming reply: the server sends incremental chunks until the reply is complete.

Request:

{
  "conversation_id": "string",
  "type": "new_message_stream_request",
  "data": {
    "content": "user message text",
    "type": "human"
  }
}

Streaming chunks (intermediate):

{
  "conversation_id": "string",
  "message_id": "string",
  "type": "stream_chunk",
  "data": {
    "content": "partial text",
    "is_final": false,
    "metrics": null
  }
}

Final chunk:

{
  "conversation_id": "string",
  "message_id": "string",
  "type": "stream_end",
  "data": {
    "content": "last chunk",
    "is_final": true,
    "metrics": {
      "token_count": 123,
      "processing_time": 1.5
    }
  }
}

Flow: The server validates the message, creates a message_id for the stream, processes with streaming, sends stream_chunk for each piece and stream_end when done, then updates cache and saves to the database.

Event: error

On validation or processing errors, the server sends an error message instead of closing the connection:

{
  "conversation_id": "string (optional)",
  "type": "error",
  "data": {
    "error": "error description",
    "details": "technical details (optional)"
  }
}

Typical cases: Invalid JSON, unknown type, invalid data shape, or errors during message handling. The connection stays open so the client can retry or send other messages.