Websocket

The NLX WebSocket API provides a persistent, bidirectional connection to your AI apps. Unlike the REST API, which requires a new HTTP handshake for every turn, the WebSocket interface allows for lower latency communication and real-time event streaming.

When to use this API

• Voice Interfaces: Where latency is critical.

• Real-time Games/Avatars: Where connection state needs to be maintained continuously.

• High-frequency Chat: Applications with very rapid back-and-forth interactions.

Connection Lifecycle

Connect (/connect)

To establish a connection, open a standard WebSocket connection to the server. All routing and authentication information is passed via Query Parameters.

URL Pattern: wss://us-east-1-ws.apps.nlx.ai

Query Parameters:

• apiKey (Required) Your NLX API Key.

• deploymentKey (Required) The unique identifier for your AI app deployment.

• channelKey (Required) The channel identifier including language suffix (e.g., xxxxxxxx-en-US).

• conversationId (Optional) ID to resume a previously active session.

Example:

const deploymentKey = 'xxxx';
const channelKey = 'xxxx-en-US';
const apiKey = 'YOUR_API_KEY';

// Construct the URL with all keys in the query string
const url = `wss://us-east-1-ws.apps.nlx.ai?deploymentKey=${deploymentKey}&channelKey=${channelKey}&apiKey=${apiKey}`;

const socket = new WebSocket(url);

socket.onopen = () => {
  console.log('Connected to NLX');
};

Connection Acknowledgement: Upon successful connection, the server will send a JSON message containing the conversationId.

{
  "conversationId": "94712479-acea-4c42-b375-e3757056b44b"
}

Send Message (/message)

To send a user turn, send a JSON payload matching the ConversationRequest structure used in the REST API.

Payload:

{
  "request": {
    "unstructured": {
      "text": "Book a flight to London"
    }
  },
  "userId": "0da722ad-cb3f-4938-a447-82ee53733362"
}

Receive Response

The server will push messages asynchronously. The payload structure matches the ConversationResponse from the REST API.

Payload:

{
  "messages": [
    {
      "text": "I can help with that. What date are you flying?",
      "type": "text",
      "messageId": "c7048e3f-3da1-4109-ab26-6c10efd96139"
    }
  ],
  "conversationId": "94712479-acea-4c42-b375-e3757056b44b"
}

Disconnect (/disconnect)

To end the session, simply close the WebSocket connection from the client side.

socket.close();

Note: The server identifies disconnected sessions using the connectionId internal header. No manual API call is required to cleanup the session state on the backend; simply dropping the socket triggers the disconnect logic.