logo
ConsoleSign Up
Document
Client API
Server API
Video Call
Server API
API Overview
Quick Start
Calling APIs
How to Call Server API Online
Global Return codes
Room Signaling APIs
Stream Mixing and Transcoding APIs
Media Service APIs
Media File APIs
Stream Moderation APIs
Callback Description
Debug using Postman
On this page

DescribeUsers

GET

https://rtc-api.zego.im/

This API allows you to query the basic status of users in a Room, including whether the User is in the Room, the User's role, the time when the User logged into the Room, etc.

Rate Limit
All Rooms under the same AppID: 10 times/second

Request

Query Parameters

    Action stringrequired

    Possible values: [DescribeUsers]

    API prototype parameter

    https://rtc-api.zego.im?Action=DescribeUsers

    AppId uint32required

    💡Public parameter. Application ID, assigned by ZEGOCLOUD. Get it from the ZEGOCLOUD Admin Console.

    SignatureNonce stringrequired

    💡Common parameter. A 16-character hexadecimal random string (hex-encoded 8-byte random number). For the generation algorithm, refer to the signature example.

    Timestamp int64required

    💡Common parameter. Current Unix timestamp in seconds. For the generation algorithm, refer to the signature example. A maximum deviation of 10 minutes is allowed.

    Signature stringrequired

    💡Common parameter. Signature used to verify the legitimacy of the request. Please refer to the signature mechanism to generate it.

    SignatureVersion stringrequired

    Possible values: [2.0]

    Default value: 2.0

    💡Public parameter. Signature version number.

    RoomId stringrequired

    Room ID.

    UserId string[]required

    Possible values: >= 1, <= 10

    List of User IDs to query the status for, supports up to 10 User IDs.

Responses​

Operation successful
Schema
    Code int32

    Return code. The following only lists some return codes related to the API business logic. For complete return codes, please refer to Global Return Codes.

    Return CodeDescriptionSuggested Action
    2Input parameter error.-
    3Input parameter length too long.Please re-enter the parameters.
    206App request QPS too high and is rate limited.Reduce request frequency, or contact ZEGOCLOUD technical support to increase the QPS limit threshold.
    50001 Room does not exist.

    📌Note:
    • 1. When there are no Users in the Room, the Room will be automatically destroyed by the server.
    • 2. When there is only one User in the Room, if that User leaves or is kicked out of the Room, the Room will be automatically destroyed by the server.
    • 3. When a User's heartbeat request times out after 100 seconds, the User will be disconnected; after all Users are no longer in the Room, the Room will be automatically destroyed by the server.
    		Please confirm whether the requested RoomId exists.
    Message string

    Description of the operation result.

    RequestId string

    Request ID.

    Data object
    UserStatusList object[]
    User status list.
  • Array[
    • UserId string

    User ID.

    Status uint32

    User status. 0: Not in the Room. 1: In the Room.

    LoginTime int64

    The time when this User logged into the Room, Unix millisecond timestamp.

    UserRole uint32

    User role.

    • 1: Host.
    • 2: Audience.
    • 4: Administrator. This type of User mainly exists in scenarios such as cloud recording and audio/video Stream review. The User-related interfaces of the client SDK will filter out this type of User.

    This return parameter is only meaningful when accessing the LiveRoom service. Please ignore this parameter when accessing the Express service.

  • ]

Previous

DescribeUserNum

Next

DescribeUserList

On this page

Back to top