# Socket.IO WebSocket Realtime API This API uses Socket.IO for real-time bidirectional communication over WebSocket connections. Unlike the REST endpoints, Socket.IO is event-based rather than request/response-based. This is a documentation-only endpoint. The actual WebSocket connection is established at the Socket.IO namespace `/api/stream-chat`. ## Connection **Connection URL**: `wss://api.agent700.ai` **Namespace**: `/api/stream-chat` **Transport**: WebSocket (with automatic fallback to polling if needed) **Authentication**: JWT token passed in the `Authorization` field of event payloads ### Connection Lifecycle 1. Client connects to the Socket.IO namespace `/api/stream-chat` 2. Client emits `send_chat_message` event with chat request and JWT token 3. Server processes the request and emits streaming response events 4. Server automatically disconnects the client after processing completes 5. Connection is closed (one message per connection pattern) The server automatically disconnects clients after processing each message to prevent connection abuse. Each chat request requires a new connection. ## Client → Server Events ### `send_chat_message` Client sends a chat completion request to the server. **Payload Schema**: See `WebSocketChatRequest` schema below. The payload structure matches the REST `/api/chat` endpoint's `ChatRequest`, but includes an additional `Authorization` field containing the JWT bearer token: ```json { "Authorization": "Bearer ", "agentId": "e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6", "messages": [ { "role": "user", "content": "Hello, how are you?" } ] } ``` ```json { "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "agentId": "e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "What is the weather today?" } ], "temperature": 0.7, "maxTokens": 1000, } ``` ## Server → Client Events The server emits the following events during chat processing: ### `chat_message_response` Streaming content chunks and metadata from the LLM response. **Payload Schema**: See `WebSocketChatMessageResponse` schema below. This event is emitted multiple times during streaming: - **Content chunks**: `{"content": "partial text", "stream_id": "..."}` - **Citations**: `{"citations": [...], "stream_id": "..."}` - **Completion**: `{"finish_reason": "stop", "safety_ratings": {...}, "stream_id": "..."}` ### `mcp_tool_message` MCP (Model Context Protocol) tool execution messages. **Payload Schema**: See `WebSocketMCPToolMessage` schema below. Emitted when MCP tools are invoked during chat processing. ### `mcp_tool_complete_in_content` Notification that an MCP tool execution has completed and the result is included in the content. **Payload Schema**: See `WebSocketMCPToolComplete` schema below. ### `scrubbed_message` Notification that message content was scrubbed for PII (Personally Identifiable Information). **Payload Schema**: See `WebSocketScrubbedMessage` schema below. ### `error` Error events indicating processing failures, authentication errors, or validation issues. **Payload Schema**: See `WebSocketErrorEvent` schema below. Common error scenarios: - **Authentication failure**: Invalid or missing JWT token - **Payment validation**: Agent owner does not have valid paid account - **Access denied**: User lacks permission to use the agent - **Processing error**: Internal error during LLM processing ## Code Examples ```javascript import { io } from 'socket.io-client'; // Connect to the Socket.IO namespace const socket = io('https://api.agent700.ai/api/stream-chat', { transports: ['websocket', 'polling'], reconnection: false // One message per connection }); // Listen for connection socket.on('connect', () => { console.log('Connected:', socket.id); // Send chat message socket.emit('send_chat_message', { Authorization: 'Bearer YOUR_JWT_TOKEN', agentId: 'e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6', messages: [ { role: 'user', content: 'Hello, how are you?' } ] }); }); // Listen for streaming responses socket.on('chat_message_response', (data) => { if (data.content) { // Append content chunk console.log('Content chunk:', data.content); } if (data.citations) { // Handle citations console.log('Citations:', data.citations); } if (data.finish_reason) { // Stream complete console.log('Finished:', data.finish_reason); console.log('Safety ratings:', data.safety_ratings); } }); // Listen for MCP tool messages socket.on('mcp_tool_message', (data) => { console.log('MCP tool message:', data.message); }); // Listen for errors socket.on('error', (data) => { console.error('Error:', data.error, 'Code:', data.code); }); // Handle disconnection socket.on('disconnect', () => { console.log('Disconnected'); }); ``` ```python import socketio # Create Socket.IO client sio = socketio.Client() @sio.event def connect(): print('Connected:', sio.sid) # Send chat message sio.emit('send_chat_message', { 'Authorization': 'Bearer YOUR_JWT_TOKEN', 'agentId': 'e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6', 'messages': [ {'role': 'user', 'content': 'Hello, how are you?'} ] }) @sio.on('chat_message_response') def on_chat_response(data): if 'content' in data: print('Content chunk:', data['content']) if 'citations' in data: print('Citations:', data['citations']) if 'finish_reason' in data: print('Finished:', data['finish_reason']) print('Safety ratings:', data.get('safety_ratings')) @sio.on('mcp_tool_message') def on_mcp_tool(data): print('MCP tool message:', data['message']) @sio.on('error') def on_error(data): print('Error:', data.get('error'), 'Code:', data.get('code')) @sio.event def disconnect(): print('Disconnected') # Connect to namespace sio.connect('https://api.agent700.ai', namespaces=['/api/stream-chat']) ``` ```bash # Note: cURL cannot directly connect to Socket.IO WebSocket # Use a WebSocket client library instead # This example shows the connection URL structure # WebSocket URL (Socket.IO handles the path): wss://api.agent700.ai/socket.io/?EIO=4&transport=websocket # Namespace connection: wss://api.agent700.ai/socket.io/?EIO=4&transport=websocket&namespace=/api/stream-chat ``` ## Error Handling ### Connection Errors - **Connection refused**: Server may be down or firewall blocking - **Timeout**: Network connectivity issues - **Namespace not found**: Invalid namespace path ### Authentication Errors The server emits an `error` event with: ```json { "error": "Unauthorized", "code": 401, "timestamp": 1234567890.123 } ``` ### Payment Validation Errors If the agent owner does not have a valid paid account: ```json { "error": "Payment required", "code": 402, "timestamp": 1234567890.123 } ``` ### Processing Errors Internal errors during LLM processing: ```json { "error": "An error occurred processing your request", "timestamp": 1234567890.123 } ``` ## Comparison with SSE Streaming The `/api/chat` endpoint with `streamingEnabled: true` provides Server-Sent Events (SSE) as an alternative to WebSocket: | Feature | WebSocket (Socket.IO) | SSE | |---------|----------------------|-----| | Transport | Bidirectional WebSocket | Unidirectional HTTP | | Connection | One message per connection | Persistent connection | | Events | Custom event names | Standard SSE format | | Reconnection | Manual (new connection) | Automatic by browser | | Client Libraries | Socket.IO client required | Native EventSource API | Choose WebSocket when you need bidirectional communication or custom event handling. Choose SSE for simpler integration with standard browser APIs. ## Security Considerations - JWT tokens must be included in each `send_chat_message` event payload - Connections are automatically closed after processing to prevent abuse - All events are logged for security monitoring - Payment validation is enforced for agent access - Rate limiting may apply (check with support for details)