Socket.IO WebSocket Realtime API

GET https://api.agent700.ai/realtime/websocket

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 <your_jwt_token>",
  "agentId": "e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6",
  "messages": [
    {
      "role": "user",
      "content": "Hello, how are you?"
    }
  ]
}

codeView complete payload example

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/TypeScriptPythoncURL

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');
});

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)