> For the complete documentation index, see [llms.txt](https://docs.klai.studio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.klai.studio/reference/apis-and-services/messaging/get-all-users-connected.md).

# Get connected users

The API endpoint `/message/users` returns the currently connected listeners for the current domain host.

A channel is considered active if there is at least one client connected to it.

## API: Return connected users

<mark style="color:green;">`POST`</mark> `https://portal.yourdomain.com/message/users`

#### Headers

| Name         | Type   | Description      |
| ------------ | ------ | ---------------- |
| accept       | string | application/json |
| content-type | string | application/json |

#### Request Body

| Name    | Type   | Description                                                                 |
| ------- | ------ | --------------------------------------------------------------------------- |
| apiKey  | string | the API key for your Klai app                                               |
| channel | string | if set, BetterForms will look up that specific channel for the current host |

## Response Shape

The response is an object keyed by channel name.

Common patterns:

* authenticated channels return arrays of `{ id, email }`
* anonymous channels return a connection count
* per-tab private channels use keys like `tab|connectionId`

Example:

```json
{
  "tab|abc123": {
    "id": "USER_ID",
    "email": "person@example.com"
  },
  "salesRoom": [
    {
      "id": "USER_1",
      "email": "a@example.com"
    },
    {
      "id": "USER_2",
      "email": "b@example.com"
    }
  ],
  "anonymousChat": 3
}
```

## Totals across pods/data centers

To get total connected counts across all pods/data centers for the current domain host, use the `/message/allusers` endpoint (POST). It authenticates with the app API key and returns per-DC counts plus a global `_total` that sums authenticated and anonymous users:

```json
{
  "apiKey": "BFAPI_..."
}
```

Default response:

```
{
  "us-east-1": { "authenticated": 12, "anonymous": 4 },
  "eu-west-1": { "authenticated": 7, "anonymous": 2 },
  "_total": { "authenticated": 19, "anonymous": 6 }
}
```

Notes:

* Keys are grouped by data center (DC) as reported by the server.
* `_total` is always present and aggregates all DCs/pods.
* Counts are scoped to the incoming host domain across all matching pods/clusters for that domain.

### Detailed admin mode

To return authenticated user details by DC, send `includeUsers: true`:

```json
{
  "apiKey": "BFAPI_...",
  "includeUsers": true
}
```

Response:

```json
{
  "us-east-1": {
    "authenticated": [
      { "id": "USER_1", "email": "a@example.com" },
      { "id": "USER_2", "email": "b@example.com" }
    ],
    "authenticatedCount": 2,
    "anonymous": 4
  },
  "_total": { "authenticated": 2, "anonymous": 4 }
}
```

By default, detailed mode de-duplicates authenticated users by `id` within each DC.

To preserve raw pod-level duplicates in the authenticated array, send `dedupeUsers: false`:

```json
{
  "apiKey": "BFAPI_...",
  "includeUsers": true,
  "dedupeUsers": false
}
```

With `dedupeUsers: false`, `authenticatedCount` reflects raw authenticated entries rather than unique users.