WebSocket Protocol

The Optave SDK uses WebSocket Secure (WSS) protocol for real-time, bidirectional communication with Optave AI services.

Connection Setup

For establishing connections and authentication, see Authentication & Connection.

Protocol Overview

The SDK uses WebSocket Secure (WSS) exclusively for all AI operations:

• Single persistent bidirectional connection
• JSON-encoded text frames
• Request-response correlation via correlation IDs
• No REST API for message operations

WebSocket Events

Standard WebSocket events:

Event	When Fired	Payload
open	Connection established	Event
message	Message received	MessageEvent
error	Error occurred	Error
close	Connection closed	CloseEvent

Close Codes

Common WebSocket close codes:

Code	Description	Action
1000	Normal closure	✅ Clean close
1001	Going away	✅ Expected close
1006	Abnormal closure	⚠️ Retry connection
1008	Policy violation	❌ Don't retry
1011	Server error	⚠️ Retry with backoff

client.on('close', (event) => {
  console.log(`Closed: ${event.code} - ${event.reason}`);

  if (event.code === 1006) {
    // Network issue - retry
    reconnect();
  }
});

Connection States

WebSocket connections have four states:

State	Value	Can Send?
CONNECTING	0	❌ No
OPEN	1	✅ Yes
CLOSING	2	❌ No
CLOSED	3	❌ No

// Check connection state
const isConnected = client.wss?.readyState === 1;

if (isConnected) {
  await client.summarize({ /* ... */ });
}

Authentication Transport

Two methods for sending authentication tokens:

Subprotocol (Default - Recommended)

Token sent via Sec-WebSocket-Protocol header:

const client = new OptaveJavaScriptSDK({
  websocketUrl: 'wss://ws-{{tenant}}.oco.optave.{{tld}}',
  tokenProvider: yourTokenProvider,
  authTransport: 'subprotocol'  // Default
});

Benefits:

• ✅ Tokens not in server logs
• ✅ More secure

Query Parameter

Token sent as URL parameter:

const client = new OptaveJavaScriptSDK({
  websocketUrl: 'wss://ws-{{tenant}}.oco.optave.{{tld}}',
  tokenProvider: yourTokenProvider,
  authTransport: 'query'
});

Use cases:

• Debugging (visible in network logs)
• Legacy server compatibility