# 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.


---

# 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.klai.studio/reference/apis-and-services/messaging/get-all-users-connected.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.