WebSocket Connection for Natural Language

The WebSocket API provides real-time, bidirectional communication for interactive AI conversations, enabling immediate responses to queries and live data updates.

Connection Setup

WebSocket URL Format

wss://app.infino.ws/fino/nl?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ACCESS_KEY%2FDATE%2Fus-east-1%2Fes%2Faws4_request&X-Amz-Date=TIMESTAMP&X-Amz-SignedHeaders=host&X-Amz-Signature=SIGNATURE

Required Headers

x-infino-client-id: <unique-client-identifier>
x-infino-thread-id: <thread-id>

Authentication

WebSocket connections use AWS Signature Version 4 authentication with query parameters. The signature must be generated using the same process as REST API requests.

URL Components

Parameter	Value	Description
X-Amz-Algorithm	AWS4-HMAC-SHA256	Fixed signing algorithm
X-Amz-Credential	ACCESS_KEY/DATE/us-east-1/es/aws4_request	Credential scope
X-Amz-Date	YYYYMMDDTHHMMSSZ	Request timestamp
X-Amz-SignedHeaders	host	Headers included in signature
X-Amz-Signature	<calculated-signature>	Request signature

Connection Example

Using websocat (WebSocket client):

# Generate signed WebSocket URL (implementation-specific)
WEBSOCKET_URL="wss://app.infino.ws/fino/nl?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=IAK_ExampleKey123456%2F20240120%2Fus-east-1%2Fes%2Faws4_request&X-Amz-Date=20240120T123000Z&X-Amz-SignedHeaders=host&X-Amz-Signature=abc123def456..."

# Connect with required headers
websocat "$WEBSOCKET_URL" \
  --header "x-infino-client-id: client-analytics-001" \
  --header "x-infino-thread-id: thread-uuid-123"

Message Protocol

Client to Server Messages

User Query Message

Send a query to the AI system for processing:

{
  "content": {
    "user_query": "Show me top 10 customers by revenue",
    "context": "customer_analysis",
    "parameters": {
      "limit": 10,
      "metric": "total_revenue",
      "time_period": "last_quarter"
    }
  },
  "type": "query"
}

Message Fields

Field	Type	Required	Description
content.user_query	string	Yes	Natural language query
content.context	string	No	Analysis context identifier
content.parameters	object	No	Query parameters and filters
type	string	Yes	Message type (query, command, ping)

Server to Client Messages

AI Response Message

Receive AI-generated analysis and results:

{
  "content": {
    "type": "result",
    "data": {
      "query_results": [
        {
          "customer_id": "cust_001",
          "name": "TechCorp Inc.",
          "total_revenue": 125000.50,
          "order_count": 45
        },
        {
          "customer_id": "cust_002",
          "name": "Global Solutions LLC", 
          "total_revenue": 98750.25,
          "order_count": 32
        }
      ],
      "total_count": 10,
      "query_metadata": {
        "execution_time": "1.2s",
        "index_used": "customer-revenue-index"
      }
    },
    "summary": "Found top 10 customers by revenue for last quarter. TechCorp Inc. leads with $125K total revenue from 45 orders.",
    "visualization": {
      "chart_type": "horizontal_bar",
      "data_points": 10,
      "recommended_view": "revenue_breakdown"
    }
  },
  "role": "assistant",
  "created_at": "2024-01-20T12:45:00Z"
}

Response Fields

Field	Type	Description
content.type	string	Response type (result, error, progress)
content.data	object	Query results and metadata
content.summary	string	Human-readable summary
content.visualization	object	Chart and visualization recommendations
role	string	Message sender (assistant, system)
created_at	string	Message timestamp

Progress Message

Real-time updates during query processing:

{
  "content": {
    "type": "progress",
    "stage": "analyzing_data",
    "progress": 0.65,
    "message": "Processing customer revenue calculations..."
  },
  "role": "system"
}

Heartbeat Message

Keep-alive messages to maintain connection:

{
  "type": "heartbeat",
  "message": "keep-alive",
  "timestamp": "2024-01-20T12:45:30Z"
}

Message Types

Query Processing Flow

1. Client sends query - User sends natural language query with context
2. Server acknowledges - Server confirms receipt and begins processing
3. Progress updates - Real-time processing status updates
4. Result delivery - Complete analysis results and data
5. Visualization suggestions - Chart and visualization recommendations

Error Handling

Error Message Format

{
  "content": {
    "type": "error",
    "error_code": "QUERY_PARSE_ERROR",
    "message": "Unable to parse natural language query",
    "details": {
      "query": "Show me undefined metrics",
      "suggestion": "Try specifying a clear metric like 'revenue' or 'customer count'"
    }
  },
  "role": "system"
}

Common Error Codes

Code	Description	Resolution
QUERY_PARSE_ERROR	Query cannot be understood	Rephrase with clearer language
INDEX_NOT_FOUND	Target index doesn't exist	Verify index name and permissions
THREAD_NOT_FOUND	Thread ID is invalid	Check that thread exists and is accessible
RATE_LIMIT_EXCEEDED	Too many concurrent queries	Wait and retry request
AUTHENTICATION_ERROR	Invalid or expired credentials	Regenerate connection signature

Connection Management

Connection States

• Connecting - Establishing WebSocket connection
• Connected - Ready to send/receive messages
• Processing - Query in progress
• Idle - Connected but no active queries
• Reconnecting - Attempting to restore connection
• Disconnected - Connection closed