# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nlx.ai/platform/developers/conversation-api/websocket.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.