WebSocket Protocol

WebSocket Protocol

The CortexPrism WebSocket provides real-time streaming chat and audio communication.

Connection

ws://127.0.0.1:3000/ws

Client → Server Messages

{ "type": "chat", "message": "Hello", "sessionId": "sess_abc123" }
{ "type": "ping" }
{ "type": "new_session" }
{ "type": "select_agent", "agentId": "agent-1" }

Chat Message Fields

Field	Type	Required	Description
type	"chat"	Yes	Message type
message	string	Yes	User message text
sessionId	string	No	Resume existing session
files	array	No	Uploaded files (base64)

Server → Client Messages

{ "type": "connected" }
{ "type": "session", "sessionId": "sess_abc123" }
{ "type": "start" }
{ "type": "chunk", "delta": "Hello" }
{ "type": "done", "tokensIn": 100, "tokensOut": 50, "costUsd": 0.001, "durationMs": 800 }
{ "type": "error", "error": "Something went wrong" }
{ "type": "pong" }

Done Message Fields

Field	Type	Description
tokensIn	number	Input tokens used
tokensOut	number	Output tokens generated
costUsd	number	Estimated cost in USD
durationMs	number	Total turn duration

Voice/Audio Messages

Client → Server:

{ "type": "audio_chunk", "data": "<base64>" }
{ "type": "audio_end" }

Server → Client:

{ "type": "speak", "text": "...", "voice": "alloy" }
{ "type": "audio", "data": "<base64>" }
{ "type": "voice_state", "enabled": true }

Session Resume

Include an existing sessionId in a chat message to resume across WebSocket reconnects and page reloads:

{ "type": "chat", "message": "Continue our conversation", "sessionId": "sess_abc123" }

The server reopens the per-session database, reactivates the session, and loads previous messages via loadHistory().

Protocol Notes

• Tool call XML (<tool_call>) and bare JSON are stripped from chunks at both server and client side
• Streaming is buffered internally when tools are registered; only clean prose reaches the client
• WebSocket connections are upgraded from standard HTTP at /ws

See Also

• REST API — HTTP API endpoints
• Voice Pipeline — Audio streaming details