Platform API

Get users' online status

Use Get users' online status to retrieve current connection state across all message gateways. Offline users remain in the response with status: 0.

HTTP request

POST {API_ADDRESS}/user/get_users_online_status

Request example

curl --request POST "${API_ADDRESS}/user/get_users_online_status" \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "operationID: ${OPERATION_ID}" \
  --header "token: ${ADMIN_TOKEN}" \
  --data-raw '{
  "userIDs": [
    "user_001",
    "user_002"
  ]
}'

Keep administrator tokens on trusted backend services only. Client applications should use user tokens issued by your backend.

Request body

{
  "userIDs": [
    "user_001",
    "user_002"
  ]
}

Parameter	Required	Type	Description
userIDs	Yes	array	List of OpenIM user IDs.

Response

OpenIM usually returns 200 OK when the request reaches the service. Use errCode in the JSON response to determine business success; errCode === 0 means the operation succeeded.

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": [
    {
      "userID": "user_001",
      "status": 1,
      "detailPlatformStatus": [
        {
          "platformID": 1,
          "connID": "conn_001",
          "isBackground": false,
          "token": "eyJhbGciOiJIUzI1Ni..."
        }
      ]
    },
    {
      "userID": "user_002",
      "status": 0,
      "detailPlatformStatus": []
    }
  ]
}

Response fields

Field	Type	Description
errCode	int	Business error code. `0` means success.
errMsg	string	Short error message.
errDlt	string	Detailed error information for troubleshooting.
data	array	Online-state results for all requested users.

`data[]` fields

Field	Type	Description
userID	string	User ID.
status	int	Online state. See `OnlineStatus`.
detailPlatformStatus	array	Active platform connection details; empty when the user is offline.
detailPlatformStatus[].platformID	int	Connected platform. See `PlatformID`.
detailPlatformStatus[].connID	string	Gateway connection ID.
detailPlatformStatus[].isBackground	bool	Whether the connection is currently in the background.
detailPlatformStatus[].token	string	User token used by the connection. Treat this value as sensitive.

Error response

When a request fails, OpenIM returns the same error envelope. See Error codes for the full handling model.

{
  "errCode": 1004,
  "errMsg": "RecordNotFoundError",
  "errDlt": ": [1004]RecordNotFoundError"
}

Scenario	Possible cause	Recommended action
Authentication failed	`token` is missing, expired, or not an administrator token.	Issue a new administrator token and keep it on the backend.
Traceability is weak	`operationID` is missing or reused across many requests.	Generate a unique `operationID` for every request and log it with the response.
Validation failed	The request body has an invalid type, missing field, or unsupported enum value.	Compare the payload with the request table and retry after correcting the fields.

Permissions and limits

This endpoint requires an application administrator token.
An offline state does not mean that the user account is missing.
Use the result for backend operations, risk controls, or service scheduling rather than exposing connection tokens to clients.

Was this page helpful?