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();

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.