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

Client connects to the Socket.IO namespace /api/stream-chat
Client emits send_chat_message event with chat request and JWT token
Server processes the request and emits streaming response events
Server automatically disconnects the client after processing completes
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:

{
  "Authorization": "Bearer <your_jwt_token>",
  "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'); });

</Tab>
<Tab title="Python">
```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

</Tab>
</Tabs>

## 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:

{
  "error": "Payment required",
  "code": 402,
  "timestamp": 1234567890.123
}

Processing Errors

Internal errors during LLM processing:

{
  "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)