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

POST 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 BF 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:

{
  "tab|abc123": {
    "id": "USER_ID",
    "email": "[email protected]"
  },
  "salesRoom": [
    {
      "id": "USER_1",
      "email": "[email protected]"
    },
    {
      "id": "USER_2",
      "email": "[email protected]"
    }
  ],
  "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:

{
  "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:

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

Response:

{
  "us-east-1": {
    "authenticated": [
      { "id": "USER_1", "email": "[email protected]" },
      { "id": "USER_2", "email": "[email protected]" }
    ],
    "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:

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

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