API Reference

Quick reference for the Optave JavaScript SDK. For detailed examples, see Usage Examples.

Constructor

new OptaveJavaScriptSDK(options)

Creates a new SDK instance.

Key Options:

• websocketUrl (string, required): WebSocket server URL
• tokenProvider (function, browser): Async function returning WebSocket token
• authenticationUrl (string, server): OAuth2 authentication endpoint
• clientId (string, server): OAuth2 client ID
• clientSecret (string, server): OAuth2 client secret (server only!)
• authTransport (string): 'subprotocol' (default) or 'query'
• connectionTimeoutMs (number): Connection timeout (default: 30000ms)
• requestTimeoutMs (number): Request timeout (default: 30000ms)
• strictValidation (boolean): Enable payload validation (default: true in dev)
• logger (object): Custom logger with debug/info/warn/error methods

Example:

const client = new OptaveJavaScriptSDK({
  websocketUrl: 'wss://ws-{{tenant}}.oco.optave.{{tld}}',
  authTransport: 'subprotocol',
  tokenProvider: async () => {
    // Replace '/api/optave-token' with your actual backend endpoint
    const res = await fetch('/api/optave-token', { method: 'POST' });
    const { token } = await res.json();
    return token;
  }
});

Connection Methods

authenticate()

Authenticates using OAuth2 client credentials (server only).

• Returns: Promise<string> - Access token
• Note: Not available in browser builds

openConnection(bearerToken?)

Establishes WebSocket connection.

• Parameters: bearerToken (string, optional) - Pre-obtained token
• Returns: Promise<Event> - Resolves when connected

closeConnection()

Closes the WebSocket connection.

cleanup()

Comprehensive cleanup of all resources (connection, listeners, pending requests).

Action Methods (Event-Based)

Send messages without waiting for responses. Listen for responses via events.

• interaction(params): Send customer interaction
• reception(params): Send reception message
• elevate(params): Request response elevation
• adjust(params): Request response adjustment
• summarize(params): Request conversation summary
• translate(params): Request translation
• recommend(params): Request recommendations
• insights(params): Request analytical insights

Events

Connection Events

• 'open': Connection established
• 'close': Connection closed
• 'error': Connection error (deprecated, use 'superpower.error')

Message Events

• 'superpower.response': Response received (recommended)
• 'superpower.error': Error occurred (recommended)
• 'message': Legacy response event (deprecated)
• 'response': Alternative response event
• 'message.{action}': Action-specific events (e.g., 'message.summarize')

Example:

client.on('superpower.response', (response) => {
  console.log('Received:', response.payload);
});

client.on('superpower.error', (error) => {
  console.error('Error:', error.message);
});

Error Structure

All errors use a structured format:

{
  category: 'AUTHENTICATION' | 'VALIDATION' | 'WEBSOCKET' | 'ORCHESTRATOR',
  code: string,
  message: string,
  details: any,
  correlationId?: string,
  timestamp: string
}

Common Error Codes:

• CONNECTION_TIMEOUT: Connection took too long
• REQUEST_TIMEOUT: Request timed out
• REQUIRED_FIELDS_MISSING: Missing required payload fields
• PAYLOAD_TOO_LARGE: Payload exceeds 128KB limit
• WEBSOCKET_NOT_IN_OPEN_STATE: Not connected