WebSocket API
The WebSocket API provides real-time streaming communication with the agent controller.
WebSocket Connection
Endpoint
Connection Parameters
| Parameter | Required | Description |
|---|---|---|
network_api_key |
Yes | Your network API key |
Connection URL Examples
Message Format
Sending Messages
Send JSON messages with the following structure:
| Field | Type | Required | Description |
|---|---|---|---|
task_id |
string | Yes | Task identifier |
text |
string | Yes | Message text to send |
context |
object | No | Additional context information |
context.url |
string | No | URL for product context |
context.lead_details |
object | No | Lead/customer details |
Example JavaScript Connection
const ws = new WebSocket('wss://data-services.aui.io/api/ia-controller/api/v1/external/session?network_api_key=your-api-key');
ws.onopen = function() {
console.log('Connected to WebSocket');
// Send a message
ws.send(JSON.stringify({
task_id: "68e78d0dc5a4b19a030d03d6",
text: "I am looking for a built-in microwave with at least 20 liters capacity",
context: {
url: "https://example.com/products",
lead_details: {
customer_type: "residential"
}
}
}));
};
ws.onmessage = function(event) {
const response = JSON.parse(event.data);
console.log('Received:', response);
};
ws.onerror = function(error) {
console.error('WebSocket error:', error);
};
ws.onclose = function() {
console.log('WebSocket connection closed');
};
Response Types
The WebSocket connection sends different types of responses during the conversation:
1. Text Content Updates
Real-time streaming of text content as it's generated:
{
"channel": {
"type": "WEBSOCKET",
"channel_name": "aeab24b2-a335-4561-976e-40f9c2b7babe",
"event_name": "thread-message-text-content-updated"
},
"scope": {
"type": "LLM_ACTIVATION_EXECUTION",
"data": {
"status": "SUCCESS"
},
"context": {
"message_id": "8a37d5ea-2182-46dc-b2ca-87584e23f227",
"task_id": "68e78d0dc5a4b19a030d03d6",
"interaction_id": "68e78d98240f9b18e0f578c8",
"pillar": "WORKFLOW"
}
},
"data": {
"text": "I found several built-in microwaves that meet your requirements..."
},
"timestamp": "2025-10-09 10:25:31.180051"
}
2. Final Message
Complete message with full response and product recommendations:
{
"id": "8af51ed1-0181-4bc8-bbc9-29949b8e26da",
"created_at": "2025-10-09 12:26:07.576000",
"text": "The BLACK+DECKER EM044KB19 Over The Range Microwave Oven is a built-in model with a spacious 1.9 cubic foot (about 54 liters) capacity, well above your 20-liter minimum. While it's an over-the-range style rather than a traditional built-in, it offers powerful 1000-watt cooking and convenient auto-cook menus. Would you like me to add this microwave to your cart?",
"sender": {
"id": "intelligent-agent",
"type": "agent",
"email": null
},
"receiver": {
"id": "user123",
"type": "user",
"email": null
},
"options": [
{
"is_recommended": false,
"widget_parameters": [
{
"title": "Product name",
"value": "BLACK+DECKER EM044KB19 Over The Range Microwave Oven with One Touch, 1000 Watts, 400 CFM and Auto...",
"type": "string"
},
{
"title": "Image link",
"value": [
"https://m.media-amazon.com/images/I/71F+1dIaF2L.jpg",
"https://m.media-amazon.com/images/I/81K22+lzVEL.jpg"
],
"type": "string"
},
{
"title": "Price",
"value": "$342.99",
"type": "numeric"
},
{
"title": "Rating",
"value": 4.4,
"type": "numeric"
},
{
"title": "Number of reviews",
"value": 11581.0,
"type": "numeric"
},
{
"title": "Description",
"value": "Pre-programmed auto menus for popcorn, potato, vegetable, pizza, snack, bacon, frozen dinner, rice, and frozen breakfast...",
"type": "string"
},
{
"title": "Item number",
"value": "B09SB8MK37",
"type": "string"
},
{
"title": "Website URL",
"value": "https://www.amazon.com/BLACK-DECKER-EM044KB19-Microwave-Stainless/dp/B09SB8MK37/",
"type": "string"
}
]
}
],
"variants_options": [],
"followup_suggestions": [
"Is installation hardware included?",
"How loud is the vent fan?",
"Any models with convection cooking?"
]
}
Response Handling
Text Streaming
Handle real-time text updates by listening for thread-message-text-content-updated events:
ws.onmessage = function(event) {
const response = JSON.parse(event.data);
if (response.channel?.event_name === 'thread-message-text-content-updated') {
// Handle streaming text
const text = response.data.text;
updateUI(text);
} else if (response.id) {
// Handle final message with options
displayFinalMessage(response);
}
};
Product Options
The final message includes product options with detailed parameters:
- Product name: Full product title
- Image link: Array of product images
- Price: Product price
- Rating: Customer rating
- Number of reviews: Review count
- Description: Product description
- Item number: Product SKU/ID
- Website URL: Direct product link
Follow-up Suggestions
Each response includes suggested follow-up questions to continue the conversation.
Error Handling
Connection Errors
ws.onerror = function(error) {
console.error('WebSocket error:', error);
// Handle connection errors
};
ws.onclose = function(event) {
if (event.code !== 1000) {
console.error('Unexpected connection close:', event.code, event.reason);
// Handle unexpected disconnections
}
};
Authentication Errors
If the API key is invalid, the connection will be closed with WebSocket code 1008 (Policy Violation).
Application Errors (4xx/5xx)
For application-level errors (non-validation, non-auth), the WebSocket will send an error message and close with WebSocket code 1008 (Policy Violation):
{
"status_code": 422,
"description": "Unprocessable Entity",
"message": "WebSocket message processing failed due to workflow constraints, please check extra_data for more context",
"extra_data": {
"method": "WebSocket",
"path": "/api/v1/external/session",
"query": "",
"task_id": "68e78d0dc5a4b19a030d03d6",
"message_type": "user_message"
}
}
Dynamic Extra Data
The extra_data field is dynamic and its content will differ based on the specific error type and context. Always check this field for additional error details relevant to your specific situation.
Internal Server Errors
For internal server errors, the WebSocket will send an error message and close with WebSocket code 1011 (Internal Error):
Error Handling Behavior
Critical: When any error occurs, the WebSocket connection will be disconnected from the server side. The error message will be the last message received before the connection closes.
WebSocket Close Codes: - 1008: Policy Violation (authentication failures, application errors) - 1011: Internal Error (server errors)
This means you should:
1. Listen for error messages in your onmessage handler
2. Handle disconnection in your onclose handler
3. Implement reconnection logic to resume the session after errors
4. Check close codes to determine the type of error that occurred
Best Practices
- Error-First Handling: Always check for error messages before processing normal responses
- Reconnection: Implement automatic reconnection for dropped connections (especially after errors)
- Message Queuing: Queue messages if the connection is not ready
- Connection Monitoring: Handle all WebSocket events (open, message, error, close)
- Rate Limiting: Avoid sending messages too frequently
- Context Preservation: Maintain context across multiple messages in the same task
- Graceful Degradation: Have fallback mechanisms when WebSocket connections fail