Skip to main content

Query user status

This method gets the status of a specified user. It checks if the specified user is in the specified channel. If the user is present, it returns the role of this user in the channel and the time of joining.

Prototype

  • Method: GET
  • Endpoint: https://api.agora.io/dev/v1/channel/user/property/{appid}/{uid}/{channelName}

Request parameters

Path parameters

Pass the following path parameters in the request URL:

ParameterTypeRequired/OptionalDescription
appidStringRequiredThe App ID of the project. You can get it through one of the following methods:
  • Copy from the Agora Console.
  • Call the Get all projects API, and read the value of the vendor_key field in the response body.
  • uidNumberRequiredThe user ID.

    Note: This parameter does not support string user accounts. Ensure that you use the integer user ID.

    channelNameStringRequiredThe channel name.

    Request header

    The Content-Type field in all HTTP request headers is application/json. All requests and responses are in JSON format. All request URLs and request bodies are case-sensitive.

    The Agora Channel Management RESTful APIs only support HTTPS. Before sending HTTP requests, you must generate a Base64-encoded credential with the Customer ID and Customer Secret provided by Agora, and pass the credential to the Authorization field in the HTTP request header. See RESTful authentication for details.

    Request examples

    Test this request in Postman or use one of the following code examples:

    Sample request:

    curl --request GET \
    --url http://api.sd-rtn.com/dev/v1/channel/user/property/appid/uid/channelName \
    --header 'Accept: application/json' \
    --header 'Authorization: '

    Response parameters

    For details about possible response status codes, see Response status codes.

    If the status code is not 200, the request fails. See the message field in the response body for the reason for this failure.

    If the status code is 200, the request succeeds, and the response body includes the following parameters:

    ParameterTypeDescription
    successBooleanThe state of this request:
    • true: Success.
    • false: Reserved for future use.
    dataObjectUser statistics, includes the following fields:
    • in_channel: Boolean. Whether the user is in the channel. When the value of in_channel is false, all other fields are not returned .
    • uid: Number. The User ID.
    • join: Number. The Unix timestamp in seconds of when the user joins the channel.
    • role: Number. The role of the user in the channel:
      • 0: Unknown user role.
      • 1: User, in a communication channel.
      • 2: Host, in the channel.
      • 3: Audience, in the channel.
    • platform: Number. The platform of the user's device. Common return values include:
      • 1: Android
      • 2: iOS
      • 5: Windows
      • 6: Linux
      • 7: Web
      • 8: macOS
      • 0: Others

    Response example

    The following is a response example for a successful request:

    {    "success": true,    "data": {        "join": 1640330382,        "uid": 2845863044,        "in_channel": true,        "platform": 7,        "role": 2    }}
    vundefined