# 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

<table data-view="cards"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><i class="fa-head-side-speak">:head-side-speak:</i></td><td><strong>Voice interfaces</strong></td><td>Where latency is critical</td></tr><tr><td><i class="fa-timer">:timer:</i></td><td><strong>Real-time games/avatars</strong></td><td>Where connection state needs to be maintained continuously</td></tr><tr><td><i class="fa-sneaker-running">:sneaker-running:</i></td><td><strong>High-frequency chat</strong></td><td>Applications with very rapid back-and-forth interactions</td></tr></tbody></table>

### 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:**

```javascript
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 acknowledgemen&#x74;**:**&#x20;

Upon successful connection, the server will send a JSON message containing the `conversationId`

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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.

```javascript
socket.close();
```

{% hint style="info" %}
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.
{% endhint %}