WebSocket API

The WebSocket API provides real-time communication for live updates, chat, and system notifications.

Connection

Endpoint

ws://localhost:8765
wss://v5.unacode.mrmaidenos.com:8765

Authentication

Include user token in connection headers or send auth message after connection.

Message Format

Outgoing Messages (Client → Server)

{
  "id": "msg_123",
  "type": "message_type",
  "payload": {},
  "timestamp": "2025-08-12T14:00:00Z"
}

Incoming Messages (Server → Client)

{
  "id": "msg_456",
  "type": "response_type",
  "payload": {},
  "timestamp": "2025-08-12T14:00:00Z",
  "user_id": "user_123"
}

Message Types

Heartbeat

Keep connection alive and check server status.

Send:

{
  "type": "heartbeat"
}

Receive:

{
  "type": "heartbeat",
  "payload": {
    "status": "alive",
    "timestamp": "2025-08-12T14:00:00Z"
  }
}

Chat Messages

Start Conversation

{
  "type": "chat",
  "action": "start_conversation"
}

Send Message

{
  "type": "chat", 
  "action": "send_message",
  "conversation_id": "conv_123",
  "content": "Hello, I need help with my project",
  "metadata": {}
}

Chat Response

{
  "type": "user_notification",
  "payload": {
    "chat_message": {
      "id": "msg_789",
      "type": "ai_response",
      "content": "I'd be happy to help! What type of project are you working on?",
      "conversation_id": "conv_123"
    }
  }
}

System Notifications

Orchestrator Status Updates

{
  "type": "orchestrator_status",
  "payload": {
    "orchestrator_id": "code_review_orchestrator",
    "status": "completed",
    "progress": 100,
    "result": {}
  }
}

Team Deployment Updates

{
  "type": "team_deployment",
  "payload": {
    "team_id": "healthcare_uc_team_v2", 
    "status": "active",
    "health": "healthy"
  }
}

Execution Progress

{
  "type": "execution_progress",
  "payload": {
    "execution_id": "exec_456",
    "progress": 75,
    "logs": [
      "Processing step 3 of 4...",
      "Analyzing results..."
    ]
  }
}

System Alerts

{
  "type": "system_alert",
  "payload": {
    "alert_type": "performance",
    "message": "High CPU usage detected",
    "severity": "warning"
  }
}

Subscription Management

Subscribe to specific message types:

{
  "type": "subscribe",
  "message_types": [
    "orchestrator_status",
    "team_deployment", 
    "system_alert"
  ]
}

Chat System Integration

Available Actions

• start_conversation - Create new chat session
• send_message - Send user message
• get_history - Retrieve chat history
• list_conversations - List user conversations
• end_conversation - Close chat session

AI Features

• Context Awareness - Maintains conversation context
• Multi-Model Support - GPT-4, Claude, local models
• Cost Tracking - Per-conversation cost monitoring
• Rate Limiting - Intelligent request throttling

JavaScript Example

class UnaCODEWebSocket {
  constructor() {
    this.ws = new WebSocket('ws://localhost:8765');
    this.ws.onmessage = this.handleMessage.bind(this);
    this.ws.onopen = this.onConnect.bind(this);
  }

  onConnect() {
    // Send heartbeat every 30 seconds
    setInterval(() => {
      this.send({ type: 'heartbeat' });
    }, 30000);
  }

  handleMessage(event) {
    const message = JSON.parse(event.data);
    console.log('Received:', message);

    switch(message.type) {
      case 'orchestrator_status':
        this.handleOrchestratorUpdate(message.payload);
        break;
      case 'user_notification':
        if (message.payload.chat_message) {
          this.handleChatMessage(message.payload.chat_message);
        }
        break;
    }
  }

  send(data) {
    this.ws.send(JSON.stringify({
      id: this.generateId(),
      timestamp: new Date().toISOString(),
      ...data
    }));
  }

  startChat() {
    this.send({
      type: 'chat',
      action: 'start_conversation'
    });
  }

  sendChatMessage(conversationId, content) {
    this.send({
      type: 'chat',
      action: 'send_message',
      conversation_id: conversationId,
      content: content
    });
  }
}

Connection States

• connecting - Initial connection attempt
• connected - Successfully connected
• disconnected - Connection lost
• reconnecting - Attempting to reconnect

Error Handling

{
  "type": "error",
  "payload": {
    "error": "Rate limit exceeded",
    "code": "RATE_LIMIT_EXCEEDED",
    "retry_after": 60
  }
}

---

Generated on 2025-08-12 14:48:04