> For the complete documentation index, see [llms.txt](https://docs.lingoql.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lingoql.com/sub0/apis-abi/websockets.md).

# Websockets

WebSockets give Sub0 a real-time channel for request-response flows and server broadcasts.

You keep using resources and actionables.

### Connect to the WebSocket route

Sub0 exposes a WebSocket route at `/ws`.

That path is configurable from your dashboard.

You can connect with or without a `uid`.

When present, `uid` helps target messages to a specific connected client.

```javascript
const socket = new WebSocket("wss://{{YOUR_SUB0_URL}}/ws");
```

```javascript
const uid = "user_12345";
const socket = new WebSocket(`wss://{{YOUR_SUB0_URL}}/ws?uid=${encodeURIComponent(uid)}`);
```

If `FORCE_WEBSOCKET_WITH_UID=true`, every connection must include a `uid`.

### Call a resource over WebSocket

Send a stringified JSON payload like this:

```json
{
  "resource": "fetch-balance",
  "action": "balance_check",
  "payload": {}
}
```

Typical response:

```json
{
  "uid": "user_12345",
  "action": "balance_check",
  "data": {}
}
```

### Protect a WebSocket resource

WebSocket resources can use the same `tokenize` and `protected` rules as HTTP endpoints.

```json
{
  "id": "fetch-balance-01",
  "resource": "fetch-balance",
  "tokenize": {
    "type": "JWT",
    "algorithm": "HS256",
    "encryption_key": "$ENV.JWT_SECRET_KEY"
  },
  "protected": {
    "provide_as": "x-access-token",
    "extract_claims": ["id"]
  },
  "actionables": [
    {
      "id": 1,
      "mode": "QUERY",
      "sql_query": {
        "query": "SELECT wallet_balance FROM users WHERE id = $1",
        "parameters": ["$PROTECTED.id"]
      },
      "returnables": ["wallet_balance"]
    }
  ]
}
```

When the resource is protected, provide the token during connection:

```javascript
const ws = new WebSocket(
  "ws://example.com/socket",
  ["x-access-token", "eyJ0eXAiO...."]
);
```

### Broadcast backend events

Use `broadcast_websocket_message` on an actionable:

```json
{
  "broadcast_websocket_message": {
    "broadcast_type": "ALL",
    "action": "wallet_balance_update"
  }
}
```

Supported broadcast types:

* `ALL`
* `SINGLE`
* `BULK`

### Important notes

* WebSocket messages must be stringified JSON.
* If the connection includes a `uid`, Sub0 injects it into object payloads as `id`.
* If you also broadcast from the same action that already returns a WebSocket response, the client can receive duplicate-looking events.
* Enable WebSockets with `ALLOW_WEBSOCKET_CONNECTIONS=true`.

### Why it matters

WebSockets let you reuse the same Sub0 execution model for real-time product moments.

That is where dashboards, alerts, balances, and live updates start to feel instant.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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.lingoql.com/sub0/apis-abi/websockets.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.