WebSocket Protocol Reference

const proto = window.location.protocol === "https:" ? "wss:" : "ws:";
const url = `${proto}//${window.location.host}/api/v1/ws`;
const ws = new WebSocket(url);

{
  "channel": "system",
  "type": "connected",
  "payload": {
    "user_id": "user-uuid",
    "channels": ["chat", "execution", "logs", "sandbox", "notifications", "system"]
  }
}

{
  "channel": "chat" | "execution" | "logs" | "sandbox" | "notifications" | "system",
  "type": "<message-type>",
  "payload": { ... }
}

{ "type": "subscribe", "channel": "notifications" }

{
  "channel": "system",
  "type": "subscribed",
  "payload": { "channel": "notifications" }
}

{ "type": "unsubscribe", "channel": "notifications" }

{
  "channel": "system",
  "type": "unsubscribed",
  "payload": { "channel": "notifications" }
}

import { orbiterSocket } from "./utils/websocket";

// Subscribe — returns an unsubscribe function
const unsubscribe = orbiterSocket.subscribe("notifications", (message) => {
  console.log("Received:", message.type, message.payload);
});

// Unsubscribe later
unsubscribe();

{ "channel": "system", "type": "ping", "payload": {} }

{ "type": "pong" }

type ConnectionState = "connecting" | "connected" | "disconnected" | "reconnecting";

orbiterSocket.onConnectionChange((state) => {
  console.log("Connection state:", state);
});

{
  "channel": "notifications",
  "type": "notification_created",
  "payload": {
    "id": "notif-uuid",
    "notification_type": "approval",
    "title": "Action Required",
    "message": "Your workflow needs approval",
    "entity_type": "workflow",
    "entity_id": "workflow-123",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

const proto = location.protocol === "https:" ? "wss:" : "ws:";
const ws = new WebSocket(`${proto}//${location.host}/api/v1/playground/${agentId}/chat`);

ws.onopen = () => {
  // Send a message
  ws.send(JSON.stringify({ content: "What is the weather today?" }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case "conversation_created":
      console.log("Conversation:", msg.conversation_id);
      break;

    case "token":
      // Append streamed text to the UI
      process.stdout.write(msg.content);
      break;

    case "tool_call":
      console.log(`Tool: ${msg.name} (${msg.duration_ms}ms)`);
      break;

    case "sandbox_result":
      if (msg.success) {
        console.log("Output:", msg.stdout);
      } else {
        console.error("Error:", msg.error || msg.stderr);
      }
      break;

    case "done":
      console.log(`\nDone: ${msg.model}, ${msg.usage.completion_tokens} tokens, ${msg.latency_ms}ms`);
      break;

    case "error":
      console.error("Error:", msg.message);
      break;
  }
};

ws.onopen = () => {
  // Load an existing conversation
  ws.send(JSON.stringify({
    type: "load_conversation",
    conversation_id: "conv-uuid-here"
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "conversation_loaded") {
    // msg.messages is an array of { id, role, content } objects
    for (const m of msg.messages) {
      console.log(`${m.role}: ${m.content}`);
    }
  }
};

// While the agent is streaming, send takeover to pause
ws.send(JSON.stringify({ type: "takeover" }));
// Server responds with takeover_ack { partial_content: "..." }

// Inject additional context
ws.send(JSON.stringify({ type: "inject", content: "Actually, focus on New York weather" }));
// Server responds with takeover_event { action: "injected", content: "..." }

// Resume generation
ws.send(JSON.stringify({ type: "resume" }));
// Server responds with takeover_event { action: "resumed" }

// Or stop completely
ws.send(JSON.stringify({ type: "stop" }));
// Server responds with takeover_stopped { partial_content: "..." }

{ "level": "error", "source": "agent", "agent_id": "agent-uuid" }

{ "type": "log", "payload": { "id": "...", "timestamp": "...", "level": "error", ... } }

{ "channel": "system", "type": "error", "payload": { "message": "..." } }

{ "type": "error", "message": "..." }

from orbiter_web.websocket import manager

# Send to all of a user's connections subscribed to a channel
sent_count = await manager.broadcast_to_user(
    user_id="user-123",
    channel="notifications",
    message={
        "type": "notification_created",
        "id": "notif-uuid",
        "notification_type": "alert",
        "title": "Alert",
        "message": "Something happened",
    },
)

await manager.send_to_connection(
    ws=websocket,
    channel="logs",
    msg_type="log",
    payload={"level": "info", "message": "Processing complete"},
)

from orbiter_web.websocket import get_ws_user

user = await get_ws_user(websocket)
if user is None:
    await websocket.close(code=4001, reason="Unauthorized")
    return
# user is a dict with: id, email, created_at