Documentation

Flexible Classroom
Console Agora.io Community Submit ticket
English
search-icon

Flexible Classroom Cloud Service RESTful API Reference

Last updated 2022/06/02 07:30:14

This page provides detailed help for the Flexible Classroom RESTful APIs.

Basic information

Server

All requests are sent to the host: api.agora.io.

Data format

The Content-Type of all requests is application/json.

Authentication

Flexible Classroom Cloud Service uses tokens for authentication. You need to put the following information to the x-agora-token and x-agora-uid fields when sending your HTTP request:

  • The RTM Token generated at your server.
  • The uid you use to generate the RTM Token.

For details, see Generate an RTM Token.

Kick a user out of a classroom

Description

Call this method to kick a specified user out of a classroom. After a successful method call, the server triggers an event indicating a user leaves the classroom. You can use the dirty parameter to determine whether the user can enter the classroom afterwards.

Prototype

  • Method: POST
  • Endpoint: /{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/users/{userUuid}/exit

Request parameters

URL parameters

Pass the following parameters in the URL.

Parameter Type Description
region String (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
  • cn: Mainland China.
  • ap: Asia Pacific.
  • eu: Europe.
  • na: North America.
    		•
    appId String (Required) Agora App ID.
    roomUuid String (Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•
    userUuid String (Required) The user ID. This is the unique identifier of the user and also the user ID used when logging in to the Agora RTM system. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•

    Request body parameters

    Pass in the following parameters in the request body.

    Parameter Type Description
    dirty Object (Optional) The user privilege:
    • state: Boolean, whether the user is dirty:
      • 1: Dirty. A dirty user cannot enter the classroom.
      • 0: Not dirty.
    • duration: Number, the duration of the dirty state (seconds), starting from the time when the user is kicked out of the classroom.

    Request example

    Request URL

    https://api.agora.io/edu/apps/{your_app_Id}/v2/rooms/test_class/users/123/exit

    Request Body

    {
    "dirty": {
        "state": 1,
        "duration": 600
    }
}

    Response parameters

    Parameter Type Description
    code Integer Business status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
    		•
    msg String The detailed information.
    ts Number The current Unix timestamp (in milliseconds) of the server in UTC.

    Response example

    {
    "msg": "Success",
    "code": 0,
    "ts": 1610167740309
}

    Set the classroom state

    Description

    Call this method to set the classroom state: Not started, Started, Ended. For details, see What classroom states does Flexible Classroom support?

    Prototype

    • Method: PUT
    • Endpoint: /{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/states/{state}

    Request parameters

    URL parameters

    Pass the following parameter in the URL.

    Parameter Type Description
    region String (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
  • cn: Mainland China.
  • ap: Asia Pacific.
  • eu: Europe.
  • na: North America.
    		•
    appId String (Required) Agora App ID.
    roomUuid String (Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•
    state Integer (Required) The classroom state:
  • 0: Not started.
  • 1: Started.
  • 2: Ended.
  • 3: The room is closed and users can no longer join the room.
    		•

    Request example

    https://api.agora.io/edu/apps/{yourappId}/v2/rooms/test_class/states/1

    Response parameters

    Parameter Type Description
    code Integer Business status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
    		•
    msg String The detailed information.
    ts Number The current Unix timestamp (in milliseconds) of the server in UTC.

    Response example

    "status": 200,
"body":
{
  "code": 0,
  "msg": "Success",
  "ts": 1610450153520
}

    Set the recording state

    Description

    Call this method to start or stop recording a specified classroom.

    Prototype

    • Method: PUT
    • Endpoint: /{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/records/states/{state}

    Request parameters

    URL parameters

    Pass the following parameter in the URL.

    Parameter Type Description
    region String (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
  • cn: Mainland China.
  • ap: Asia Pacific.
  • eu: Europe.
  • na: North America.
    		•
    appId String (Required) Agora App ID.
    roomUuid String (Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•
    state Integer (Required) The recording state:
  • 0: Stop recoding.
  • 1: Started.
    		•

    Request body parameters

    Pass in the following parameters in the request body.

    Parameter Type Description
    mode String (Optional) The recording mode:
  • Set this parameter as web to enable web page recording mode. The format of recorded files is MP4. When the length of the recorded file reaches around two hours, or when the size of the file exceeds around 2 GB, the recording service automatically creates another MP4 file.
  • If you do not set this parameter, Flexible Classroom records the audio and video of the teachers in composite recording mode by default. The format of recorded files is M3U8 and TS.
    		•
    webRecordConfig Object (Optional) When the mode is set as web, you need to set the detailed configuration of the web page recording through webRecordConfig, including the following fields:
    • url: (Required) String, the address of the web page to record. If you want to record a certain flexible classroom, you need to pass in the parameters required for launching a classroom in the URL. The Agora Cloud Recording service can join the specified classroom as an "invisible user" for recording. See the URL example in the request example. The following parameters are required in the URL:
      • userUuid: The user ID used by the Agora Cloud Recording service. Please ensure that the user ID used by the Agora Cloud Recording service is not the same as that of existing users in the classroom, otherwise, the Agora Cloud Recording service will fail to join the classroom.
      • roomUuid: The ID of the classroom to be recorded.
      • roomType: The type of the classroom to be recorded.
      • roleType: The role of the Agora Cloud Recording service in the classroom to be recorded. Set this parameter as 0.
      • pretest: Whether to enable the pre-class test. Set this parameter as false.
      • rtmToken: The RTM Token used by the Agora Cloud Recording service.
      • language: The language of the user interface. Set this parameter as zh or en.
      • appId: Your Agora App ID.
    • rootUrl: (Required) String, the root address of the web page to be recorded. During the recording, Agora Edu Cloud Service automatically gets the full address of the web page to be recorded by putting rootUrl, roomUuid, roomType,and other parameters together. If you set both url and rootUrl, url overrides rootUrl.
    • onhold: (Required) Boolean. You can set this parameter as:
      • true: Pauses recording immediately after the web page recording task is enabled. The recording service opens and renders the web page to be recorded, but does not generate a slice file.
      • false: (Default) Enables the web page recording task and starts recording.
    • videoBitrate: (Optional) Number. The bitrate of the video (Kbps). The value range is [50, 8000]. The default value of videoBitrate varies according to the resolution of the output video:
      • If the resolution of the output video is less than 1280 × 720, the default value of videoBitrate is 1500.
      • If the resolution of the output video is greater than or equal to 1280 × 720, the default value of videoBitrate is 2000.
    • videoFps: (Optional) Number. The frame rate of the video (fps). The value range is [5, 60]. The default value is 15.
    • audioProfile: (Optional) Number. The sample rate, encoding mode, number of audio channels, and bitrate.
      • 0: (Default) Sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 48 Kbps.
      • 1: Sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 128 Kbps.
      • 2: Sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 192 Kbps.
    • videoWidth: Number. The width of the video (pixels). The value range is [480, 1280]. The default value is 1280. The product of videoWidth and videoHeight should not exceed 921,600 (1280 × 720).
    • videoHeight: Number. The height of the video (pixels). The value range is [480, 1280]. The default value is 720. The product of videoWidth and videoHeight should not exceed 921,600 (1280 × 720).
    • maxRecordingHour: Number, the maximum recording length (hours). The value range is [1,720]. If you set the class duration, Agora Edu Cloud Service gets the maximum recording length by rounding up the class duration. For example, if the class duration is 1800 seconds, maxRecordingHour is one hour. If you do not set the class duration, the default value of maxRecordingHour is two hours. If the limit set by maxRecordingHour is exceeded, the recording stops automatically.
    retryTimeout Number The amount of time (seconds) that the Flexible Classroom cloud service waits between tries. The Flexible Classroom cloud service reties twice at most.

    Request example

    Request URL

    https://api.agora.io/edu/apps/{yourappId}/v2/rooms/test_class/records/states/1

    Request Body

    {
    "mode": "web",
    "webRecordConfig": {
        "url":"https://webdemo.agora.io/xxxxx/?userUuid={recorder_id}&roomUuid={room_id_to_be_recorded}&roleType=0&roomType=4&pretest=false&rtmToken={recorder_token}&language=en&appId={your_app_id}",
        "rootUrl":"https://xxx.yyy.zzz"
    },
    "retryTimeout": 60
}

    Response parameters

    Parameter Type Description
    code Integer Business status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
    		•
    msg String The detailed information.
    ts Number The current Unix timestamp (in milliseconds) of the server in UTC.

    Response example

    "status": 200,
"body":
{
    "code": 0,
    "ts": 1610450153520
}

    Update the recording configurations

    Description

    Call this method during the recording to update the recording configurations. Every time this method is called, the previous configurations are overwritten.

    Prototype

    • Method: PUT
    • Endpoint: /{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/records/states/{state}

    Request parameters

    URL parameters

    Pass the following parameter in the URL.

    Parameter Type Description
    region String (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
  • cn: Mainland China.
  • ap: Asia Pacific.
  • eu: Europe.
  • na: North America.
    		•
    appId String (Required) Agora App ID.
    roomUuid String (Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•

    Request body parameters

    Pass in the following parameters in the request body.

    Parameter Type Description
    webRecordConfig Object (Optional) Recording configurations:
    • onhold: (Required) Boolean. You can set this parameter as:
      • true: Pauses the web page recording. The recording service no longer generates any slice file.
      • false: (Default) Continues the web page recording. After the recording is paused, you can call this method and set the onhold parameter as false to continue the web page recording.

    Request example

    Request URL

    https://api.agora.io/edu/apps/{yourappId}/v2/rooms/test_class/records/states/1

    Request Body

    {
    "webRecordConfig": {
        "onhold": false
    }
}

    Response parameters

    Parameter Type Description
    code Integer Business status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
    		•
    msg String The detailed information.
    ts Number The current Unix timestamp (in milliseconds) of the server in UTC.

    Response example

    "status": 200,
"body":
{
    "code": 0,
    "ts": 1610450153520
}

    Get the recording list

    Description

    Get the recording list in a specified classroom.

    You can fetch data in batches with the nextId parameter. You can get up to 100 pieces of data for each batch.

    Prototype

    • Method: GET
    • Endpoint: /{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/records

    Request parameters

    URL parameters

    Pass the following parameter in the URL.

    Parameter Type Description
    region String (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
  • cn: Mainland China.
  • ap: Asia Pacific.
  • eu: Europe.
  • na: North America.
    		•
    appId String (Required) Agora App ID.
    roomUuid String (Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•

    Query parameters

    Parameter Type Description
    nextId String (Optional) The starting ID of the next batch of data. When you call this method to get the data for the first time, leave this parameter empty or set it as null. Afterward, you can set this parameter as the nextId that you get in the response of the previous method call.

    Request example

    Example one:

    https://api.agora.io/edu/apps/{yourappId}/v2/rooms/test_class/records?null

    Example two:

    https://api.agora.io/edu/apps/{yourappId}/v2/rooms/test_class/records?nextId=xxx

    Response parameters

    Parameter Type Description
    code Integer Business status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
    		•
    msg String The detailed information.
    ts Number The current Unix timestamp (in milliseconds) of the server in UTC.
    data Object Include the following parameters:
    • count: Integer, the number of pieces of data in this batch.
    • list: JSONArray. An array of the recording list. A JSON object includes the following parameters:
      • appId: Your Agora App ID.
      • roomUuid: The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel.
      • recordId: The unique identifier of a recording session. A recording session starts when you call a method to start recording and ends when you call this method to stop recording.
      • startTime: The UTC timestamp when a recording session starts, in milliseconds.
      • endTime: The UTC timestamp when a recording session ends, in milliseconds.
      • resourceId: The resourceId of the Agora Cloud Recording service.
      • sid: The sid of the Agora Cloud Recording service.
      • recordUid: The UID used by the Agora Cloud Recording service in the channel.
      • boardAppId: The App Identifier of the Agora Interactive Whiteboard service.
      • boardToken: The SDK Token of the Agora Interactive Whiteboard service.
      • boardId: The unique identifier of a whiteboard session.
      • type: Integer, the recording type:
        • 1: Individual Recording
        • 2: Composite Recording
      • status: Integer, the recording state:
        • 1: In recording.
        • 2: Recording has ended.
      • url: String, the URL address of the recorded files in composite recording mode.
      • recordDetails: JSONArray. The JSON object contains the following fields:
        • url: String, the URL address of the recorded files in web page recording mode.
      • nextId: String, the starting ID of the next batch of data. If it is null, there is no next batch of data. If it is not null, use this nextId to continue the query until null is reported.
      • total: Integer, the total number of pieces of data.

    Response example

    "status": 200,
"body":
{
    "code": 0,
    "msg": "Success",
    "ts": 1610450153520,
    "data": {
      "total": 17,
      "list": [
          {
            "recordId": "xxxxxx",
            "appId": "xxxxxx",
            "roomUuid": "jason0",
            "startTime": 1602648426497,
            "endTime": 1602648430262,
            "resourceId": "xxxxxx",
            "sid": "xxxxxx",
            "recordUid": "xxxxxx",
            "boardId": "xxxxxx",
            "boardToken": "xxxxxx",
            "type": 2,
            "status": 2,
            "url": "scenario/recording/xxxxxx/xxxxxx/xxxxxx.m3u8",
            "recordDetails":[
                {
                    "url":"xxxx/xxxx.mp4"
                }
            ]
          },
          {...},
      ],
      "count": 17
    }
}

    Upload a public resource

    Description

    Call this method to upload a public resource to the specified classroom. All users in the classroom can see these public resources.

    Prototype

    • Method: PUT
    • Endpoint: /{region}/edu/apps/{appId}/v1/rooms/{roomUuid}/resources/{resourceUuid}

    Request parameters

    URL parameters

    Pass the following parameters in the URL.

    Parameter Type Description
    region String (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
  • cn: Mainland China.
  • ap: Asia Pacific.
  • eu: Europe.
  • na: North America.
    		•
    appId String (Required) Agora App ID.
    roomUuid String (Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•
    resourceUuid String (Required) The resource ID. This is the unique identifier of a file. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•

    Request body parameters

    Pass in the following parameters in the request body.

    Parameter Type Description
    resourceName String The resource name for display in the classroom. The string length must be less than 64 bytes.
    size Number (Required) The size (bytes) of the resource.
    ext String (Required) The resource extension:
    • "ppt"
    • "pptx"
    • "pptm"
    • "docx"
    • "doc"
    • "xlsx"
    • "xls"
    • "csv"
    • "pdf"
    url String (Required) The URL address of the resource, such as "https://xxx.com".
    conversion Object (Optional) If you want to display resources such as a PPT on the whiteboard in the classroom, you need to set conversion to convert the resource into a static image or a dynamic HTML page. conversion contains the following fields:
    • type: (Required) String, the conversion type:
      • "static": Convert the file to a static picture. If the file extension is "ppt", "doc", "docx", or "pdf", you can enable static conversion.
      • "dynamic": Convert the file to a dynamic HTML page. When the extension is "pptx", you can enable the dynamic conversion.
    • preview: (Optional) Boolean, whether to generate a preview image. This parameter is valid only when type is "dynamic".
      • true: Generate a preview image.
      • false: (Default) Do not generate a preview image.
    • scale: (Optional) Number, the scale factor. The range is [0.1,3.0], and the default value is 1.2. This parameter is valid only when type is "static".
    • outputFormat: (Optional) String, the format of theoutput picture. You can set this parameter as "png", "jpg", "jpeg", or "webp". The default value is "png". This parameter is valid only when type is "static".

    Request example

    Request URL

    https://api.agora.io/edu/apps/{your_app_Id}/v1/rooms/test_class/resources/class_file_1

    Request Body

    {
    "resourceName": "class_file",
    "size": 1024,
    "ext":"ppt",
    "url":"https://xxx.com",
    "conversion": {
        "type":"static",
        "preview": false,
        "scale": 1.2,
        "outputFormat": ""
    },
}

    Response parameters

    Parameter Type Description
    code Integer Business status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
    		•
    msg String The detailed information.
    ts Number The current Unix timestamp (in milliseconds) of the server in UTC.
    data Object Array An array of republic resources. Each object represents a public resource and contains the following fields:
    • resourceUuid: String. The resource ID. This is the unique identifier of a file.
    • resourceName: String, the resource name for display in the classroom.
    • ext: String, the resource extension.
    • size: Number, the resource size (bytes).
    • url: String, the URL address of the resource.
    • updateTime: Number, the update time of the resource, Unix timestamp (in milliseconds), UTC time.
    • convert: Boolean, whether to enable file conversion.
    • taskUuid: String, the ID of the file conversion task.
    • taskToken: String, the token used by the file conversion task.
    • taskProgress: Object, the progress of the file conversion task, including the following fields:
      • totalPageSize: Number, the total number of pages in the file.
      • convertedPageSize: Number, the number of pages that have been converted.
      • convertedPercentage: Number, the progress (percentage) of the conversion task.
      • convertedFileList: Object array, the list of converted pages. Each object represents a converted page and contains the following fields:
        • name: String. The page name.
        • ppt: Object, a PPT page, containing the following fields:
          • width: Number, the page width (pixel).
          • height: Number. The page height (pixel).
          • src: String, the URL address of the converted page.
          • preview: String, the URL address of the preview image. This field is only available when the type is set as "dynamic" and preview is set as true.
        • currentStep: The current step of the conversion task. This field is only available when the type is "dynamic". This field can be "Extracting", "Packaging", "GeneratingPreview", or "MediaTranscode".

    Response example

    {
    "msg":"Success",
    "code":0,
    "ts":1610433913533,
    "data":{
        "resourceUuid": "class_file_1",
        "resourceName": "class_file",
        "ext": "ppt",
        "size": 1024,
        "url": "https://xxx.com",
        "updateTime": 0,
        "convert": true,
        "taskUuid":"",
        "taskToken":"",
        "taskProgress": {
            "totalPageSize": 10,
            "convertedPageSize": 3,
            "convertedPercentage": 30,
            "convertedFileList": [{
                "name": 1,
                "ppt":{
                    "width": 1024,
                    "height": 960,
                    "src": "xxxx://xxxx.xxx.xx/xxxx.xxx",
                    "preview": "xxxx://xxxx.xxx.xx/xxxx.xxx",
                }
            },{...}],
            "currentStep": "Extracting"
        }
    }
}

    Delete public resources

    Description

    Delete one or multiple public resources in the specified classroom.

    Prototype

    • Method: DELETE
    • Endpoint: /{region}/edu/apps/{appId}/v1/rooms/{roomUuid}/resources

    Request parameters

    URL parameters

    Pass the following parameters in the URL.

    Parameter Type Description
    region String (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
  • cn: Mainland China.
  • ap: Asia Pacific.
  • eu: Europe.
  • na: North America.
    		•
    appId String (Required) Agora App ID.
    roomUuid String (Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•

    Request body parameters

    Pass in the following parameters in the request body.

    Parameter Type Description
    resourceUuids String array (Required) An array of resource IDs. The resource ID is the unique identifier of a resource. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•

    Request example

    Request URL

    https://api.agora.io/edu/apps/{your_app_Id}/v1/rooms/test_class/resources

    Request Body

    {
    "resourceUuids": ["uuid1","uuid2"]
}

    Response parameters

    Parameter Type Description
    code Integer Business status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
    		•
    msg String The detailed information.
    ts Number The current Unix timestamp (in milliseconds) of the server in UTC.

    Response example

    {
    "msg":"Success",
    "code":0,
    "ts":1610433913533
}

    Get public resources

    Description

    Get all public resources in the specified classroom.

    Prototype

    • Method: GET
    • Endpoint: /{region}/edu/apps/{appId}/v1/rooms/{roomUuid}/resources

    Request parameters

    URL parameters

    Pass the following parameters in the URL.

    Parameter Type Description
    region String (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
  • cn: Mainland China.
  • ap: Asia Pacific.
  • eu: Europe.
  • na: North America.
    		•
    appId String (Required) Agora App ID.
    roomUuid String (Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•

    Request example

    Request URL

    https://api.agora.io/edu/apps/{your_app_Id}/v1/rooms/test_class/resources

    Response parameters

    Parameter Type Description
    code Integer Business status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
    		•
    msg String The detailed information.
    ts Number The current Unix timestamp (in milliseconds) of the server in UTC.
    data Object Array An array of republic resources. Each object represents a public resource and contains the following fields:
    • resourceUuid: String. The resource ID. This is the unique identifier of a file.
    • resourceName: String, the resource name for display in the classroom.
    • ext: String, the resource extension.
    • size: Number, the resource size (bytes).
    • url: String, the URL address of the resource.
    • updateTime: Number, the update time of the resource, Unix timestamp (in milliseconds), UTC time.
    • convert: Boolean, whether to enable file conversion.
    • taskUuid: String, the ID of the file conversion task.
    • taskToken: String, the token used by the file conversion task.
    • taskProgress: Object, the progress of the file conversion task, including the following fields:
      • totalPageSize: Number, the total number of pages in the file.
      • convertedPageSize: Number, the number of pages that have been converted.
      • convertedPercentage: Number, the progress (percentage) of the conversion task.
      • convertedFileList: Object array, the list of converted pages. Each object represents a converted page and contains the following fields:
        • name: String. The page name.
        • ppt: Object, a PPT page, containing the following fields:
          • width: Number, the page width (pixel).
          • height: Number. The page height (pixel).
          • src: String, the URL address of the converted page.
          • preview: String, the URL address of the preview image. This field is only available when the type is set as "dynamic" and preview is set as true.
      • currentStep: The current step of the conversion task. This field is only available when the type is "dynamic". This field can be "Extracting", "Packaging", "GeneratingPreview", or "MediaTranscode".

    Response example

    {
    "msg":"Success",
    "code":0,
    "ts":1610433913533,
    "data":[{
        "resourceUuid": "",
        "resourceName": "",
        "ext": "",
        "size": 0,
        "url": "",
        "updateTime": 0,
        "convert": true,
        "taskUuid":"",
        "taskToken":"",
        "taskProgress": {
            "totalPageSize": 10,
            "convertedPageSize": 3,
            "convertedPercentage": 30,
            "convertedFileList": [{
                "name": 1,
                "ppt":{
                    "width": 1024,
                    "height": 960,
                    "src": "xxxx://xxxx.xxx.xx/xxxx.xxx",
                    "preview": "xxxx://xxxx.xxx.xx/xxxx.xxx",
                }
            },{...}],
            "currentStep": "Extracting"
        }
    }]
}

    Query a specified event

    Description

    Query a specified type of event in a specified classroom.

    You can fetch data in batches with the nextId parameter. You can get up to 100 pieces of data for each batch.

  • You can query the same event repeatedly.
  • You cannot query events in a destroyed classroom. A classroom is destroyed automatically one hour after it is ended.

    • Prototype

    • Method: GET
    • Endpoint: /{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/sequences

    Request parameters

    URL parameters

    Pass the following parameters in the URL.

    Parameter Type Description
    region String (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
  • cn: Mainland China.
  • ap: Asia Pacific.
  • eu: Europe.
  • na: North America.
    		•
    appId String (Required) Agora App ID.
    roomUuid String (Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•

    Query parameters

    Parameter Type Description
    nextId String (Optional) The starting ID of the next batch of data. When you call this method to get the data for the first time, leave this parameter empty or set it as null. Afterward, you can set this parameter as the nextId that you get in the response of the previous method call.
    cmd Integer (Optional) Event type. For details, see Flexible Classroom Cloud Service Events.

    Request example

    Request URL

    Example one:

    https://api.agora.io/edu/apps/{appId}/v2/rooms/test_class/sequences?null&cmd=1

    Example two:

    https://api.agora.io/edu/apps/{appId}/v2/rooms/test_class/sequences?nextId=50&cmd=1

    Response parameters

    Parameter Type Description
    code Integer Business status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
    		•
    msg String The detailed information.
    ts Number The current Unix timestamp (in milliseconds) of the server in UTC.
    data Object Include the following parameters:
    • total: Integer, the total number of pieces of data.
    • count: Integer, the number of pieces of data in this batch.
    • list: JSONArray. An array of the recording list. A JSON object includes the following parameters:
      • roomUuid: String, the classroom ID.
      • cmd: Integer, the event type. For details, see Flexible Classroom Cloud Service Events.
      • sequence: Integer. The event ID. This is the unique identifier of an event, which is automatically generated to ensure the order of events.
      • version: Integer, the service version.
      • data: Object, the detailed data of the event. The data varies depending on the event type. For details, see Flexible Classroom Cloud Service Events.
    • nextId: String, the starting ID of the next batch of data. If it is null, there is no next batch of data. If it is not null, use this nextId to continue the query until null is reported.

    Response example

    {
    "msg":"Success",
    "code":0,
    "ts":1610433913533,
    "data":{
        "total":1,
        "list":[
            {
                "roomUuid": "",
                "cmd": 20,
                "sequence": 1,
                "version": 1,
                "data":{}
            }
        ],
        "nextId": null,
        "count":1
    }
}

    Get classroom events

    Description

    Get all events in the classrooms associated with a specified App ID.

    You can call this method at regular intervals to listen for all the events that occur in the flexible classrooms.

  • Each event can only be obtained once.
  • Note: You cannot get events one hour after a classroom is destroyed.

    • Prototype

    • Method: GET
    • Endpoint: /{region}/edu/polling/apps/{appId}/v2/rooms/sequences

    Request parameters

    URL parameters

    Pass the following parameter in the URL.

    Parameter Type Description
    region String (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
  • cn: Mainland China.
  • ap: Asia Pacific.
  • eu: Europe.
  • na: North America.
    		•
    appId String (Required) Agora App ID.

    Request example

    https://api.agora.io/edu/polling/apps/{yourappId}/v2/rooms/sequences

    Response parameters

    Parameter Type Description
    code Integer Business status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
    		•
    msg String The detailed information.
    ts Number The current Unix timestamp (in milliseconds) of the server in UTC.
    data Object Include the following parameters:
  • roomUuid: String, the classroom ID.
  • cmd: Integer, the event type. For details, see Flexible Classroom Cloud Service Events.
  • sequence: Integer. The event ID. This is the unique identifier of an event, which is automatically generated to ensure the order of events.
  • version: Integer, the service version.
  • data: Object, the detailed data of the event. The data varies depending on the event type. For details, see Flexible Classroom Cloud Service Events.
    		•

    Response example

    "status": 200,
"body":
{
    "msg": "Success",
    "code": 0,
    "ts": 1610167740309,
    "data":[
        {
            "roomUuid": "xxxxxx",
            "cmd": 20,
            "sequence": 1,
            "version": 1,
            "data":{}
        }
    ]
}

    Update custom classroom properties

    Description

    Add or update the custom properties of a specified classroom. For details, see How can I set user properties and classroom properties?

    Prototype

    • Method: PUT
    • Endpoint: /{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/properties

    Request parameters

    URL parameters

    Pass the following parameters in the URL.

    Parameter Type Description
    region String (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
  • cn: Mainland China.
  • ap: Asia Pacific.
  • eu: Europe.
  • na: North America.
    		•
    appId String (Required) Agora App ID.
    roomUuid String (Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•

    Request body parameters

    Pass in the following parameters in the request body.

    Parameter Type Description
    properties Object Classroom properties.
    cause Object The update reason.

    Request example

    Request Body

    {
    "properties" :{
        "key1":"value1",
        "key2":"value2"
    },
    "cause":{}
}

    Response parameters

    Parameter Type Description
    code Integer Business status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
    		•
    msg String The detailed information.
    ts Number The current Unix timestamp (in milliseconds) of the server in UTC.

    Response example

    {
    "msg": "Success",
    "code": 0,
    "ts": 1610167740309
}

    Delete custom classroom properties

    Description

    Delete the custom properties of a specified classroom. For details, see How can I set user properties and classroom properties?

    Prototype

    • Method: DELETE
    • Endpoint: /{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/properties

    Request parameters

    URL parameters

    Pass the following parameters in the URL.

    Parameter Type Description
    region String (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
  • cn: Mainland China.
  • ap: Asia Pacific.
  • eu: Europe.
  • na: North America.
    		•
    appId String (Required) Agora App ID.
    roomUuid String (Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•

    Request body parameters

    Pass in the following parameters in the request body.

    Parameter Type Description
    properties String array Classroom properties.
    cause Object Reason for deletion.

    Request example

    Request Body

    {
    "properties" :[
        "key1",
        "key2"
    ],
    "cause":{}
}

    Response parameters

    Parameter Type Description
    code Integer Business status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
    		•
    msg String The detailed information.
    ts Number The current Unix timestamp (in milliseconds) of the server in UTC.

    Response example

    {
    "msg": "Success",
    "code": 0,
    "ts": 1610167740309
}

    Update custom user properties

    Description

    Add or update the custom properties of a specified user. For details, see How can I set user properties and classroom properties?

    Prototype

    • Method: PUT
    • Endpoint: /{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/users/{userUuid}/properties

    Request parameters

    URL parameters

    Pass the following parameters in the URL.

    Parameter Type Description
    region String (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
  • cn: Mainland China.
  • ap: Asia Pacific.
  • eu: Europe.
  • na: North America.
    		•
    appId String (Required) Agora App ID.
    roomUuid String (Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•
    userUuid String (Required) The user ID. This is the unique identifier of the user and also the user ID used when logging in to the Agora RTM system. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•

    Request body parameters

    Pass in the following parameters in the request body.

    Parameter Type Description
    properties Object The user properties.
    cause Object The update reason.

    Request example

    Request Body

    {
    "properties" :{
        "key1":"value1",
        "key2":"value2"
    },
    "cause":{}
}

    Response parameters

    Parameter Type Description
    code Integer Business status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
    		•
    msg String The detailed information.
    ts Number The current Unix timestamp (in milliseconds) of the server in UTC.

    Response example

    {
    "msg": "Success",
    "code": 0,
    "ts": 1610167740309
}

    Delete custom user properties

    Description

    Delete the custom properties of a specified user. For details, see How can I set user properties and classroom properties?

    Prototype

    • Method: DELETE
    • Endpoint: /{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/users/{userUuid}/properties

    Request parameters

    URL parameters

    Pass the following parameters in the URL.

    Parameter Type Description
    region String (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
  • cn: Mainland China.
  • ap: Asia Pacific.
  • eu: Europe.
  • na: North America.
    		•
    appId String (Required) Agora App ID.
    roomUuid String (Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•
    userUuid String (Required) The user ID. This is the unique identifier of the user and also the user ID used when logging in to the Agora RTM system. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•

    Request body parameters

    Pass in the following parameters in the request body.

    Parameter Type Description
    properties String array The user properties.
    cause Object Reason for deletion.

    Request example

    Request Body

    {
    "properties" :[
        "key1",
        "key2"
    ],
    "cause":{}
}

    Response parameters

    Parameter Type Description
    code Integer Business status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
    		•
    msg String The detailed information.
    ts Number The current Unix timestamp (in milliseconds) of the server in UTC.

    Response example

    {
    "msg": "Success",
    "code": 0,
    "ts": 1610167740309
}

    Set the extApp properties

    Description

    Add or update the properties of the extApp in a specified classroom.

    Prototype

    • Method: PUT
    • Endpoint: /{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/extApps/{extAppUuid}/properties

    Request parameters

    URL parameters

    Pass the following parameters in the URL.

    Parameter Type Description
    region String (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
  • cn: Mainland China.
  • ap: Asia Pacific.
  • eu: Europe.
  • na: North America.
    		•
    appId String (Required) Agora App ID.
    roomUuid String (Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•
    extAppUuid String (Required) The extApp ID. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•

    Request body parameters

    Pass in the following parameters in the request body.

    Parameter Type Description
    properties Object The user properties.
    common Object The JSON object contains the following fields:
  • state: Integer, the state of extApp. 0 means disabled, and 1 means enabled.
    		•
    cause Object The update reason.

    Request example

    Request Body

    {
    "properties" :{},
    "common":{
        "state":0
    },
    "cause":{}
}

    Response parameters

    Parameter Type Description
    code Integer Business status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
    		•
    msg String The detailed information.
    ts Number The current Unix timestamp (in milliseconds) of the server in UTC.

    Response example

    {
    "msg": "Success",
    "code": 0,
    "ts": 1610167740309
}

    Delete the extApp properties

    Description

    Delete the properties of the extApp in a specified classroom.

    Prototype

    • Method: DELETE
    • Endpoint: /{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/extApps/{extAppUuid}/properties

    Request parameters

    URL parameters

    Pass the following parameters in the URL.

    Parameter Type Description
    region String (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
  • cn: Mainland China.
  • ap: Asia Pacific.
  • eu: Europe.
  • na: North America.
    		•
    appId String (Required) Agora App ID.
    roomUuid String (Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•
    extAppUuid String (Required) The extApp ID. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•

    Request body parameters

    Pass in the following parameters in the request body.

    Parameter Type Description
    properties String array The user properties.
    cause Object Reason for deletion.

    Request example

    Request Body

    {
    "properties" :[
        "key-path1",
        "key-path2"
    ],
    "cause":{}
}

    Response parameters

    Parameter Type Description
    code Integer Business status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
    		•
    msg String The detailed information.
    ts Number The current Unix timestamp (in milliseconds) of the server in UTC.

    Response example

    {
    "msg": "Success",
    "code": 0,
    "ts": 1610167740309
}

    Get data for pop-up quizzes

    Prototype

    • Method: GET
    • Request path: /edu/apps/{appId}/v2/rooms/{roomUuid}/widgets/popupQuiz/sequences

    Request parameters

    URL parameters

    Pass the following parameters in the URL:

    Parameter Type Description
    appId String (Required) Agora App ID.
    roomUuid String (Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 bytes.

    Query parameters

    Parameter Type Description
    nextId String (Optional) The starting ID of the next batch of data. When you call this method to get the data for the first time, leave this parameter empty or set it as null. Afterward, you can set this parameter as the nextId that you get in the response of the previous method call.
    count Integer (Optional) The number of pieces of data in this batch. The default value is 100.

    Response parameters

    The fields returned in data vary in different situations.

    • After the teacher clicks the Start button to start a quiz, the summarized data of the Pop-up Quiz widget updates. data contains the following fields:

      Field name Type Description
      action Integer The action type
      changeProperties Object The changed properties
      changeProperties.extra Object The extra information of the changed properties
      changeProperties.extra.correctItems Object[] The correct choice
      changeProperties.extra.correctCount Integer The number of students who have made the correct choice
      changeProperties.extra.answerState Integer The status of this quiz:
      • 1 : In progress
      • 0: Ended
      changeProperties.extra.receiveQuestionTime Long The time when the students receive the question
      changeProperties.extra.popupQuizId String The question ID
      changeProperties.extra.averageAccuracy Float The rate at which the correct choice is made for this question
      changeProperties.extra.totalCount Integer The total number of students who have submitted their answers to this question
      changeProperties.extra.items Object[] The options of this question
      changeProperties.state Integer The state of the Pop-up Quiz widget:
      • 0: Inactive
        • 1: Active
      cause String The reason for the property change
      operator Object The operator of the property change
      operator.userUuid String The ID of the operator
      operator.userName String The name of the operator
      operator.role String The role of the operator

    • After a student submits the answer, the student's data updates. data contains the following fields:

      Field name Type Description
      action Integer The action type
      changeProperties Object The changed properties
      changeProperties.lastCommitTime Long The last submit time
      changeProperties.popupQuizId String The question ID
      changeProperties.selectedItems Object[] The answer submitted by this student
      changeProperties.isCorrect Boolean Whether the answer submitted by the student is correct
      cause String The reason for the property change
      operator Object The operator of the property change
      operator.userUuid String The ID of the operator
      operator.userName String The name of the operator
      operator.role String The role of the operator
      fromUser Object The user who starts this quiz
      fromUser.userUuid String The ID of the user who starts this quiz
      fromUser.userName String The name of the user who starts this quiz
      fromUser.role String The role of the user who starts this quiz

    • After a student submits the answer, the summarized data of the Pop-up Quiz widget updates. data contains the following fields:

      Field name Type Description
      action Integer The action type
      changeProperties Object The changed properties
      changeProperties.extra Object The extra information of the changed properties
      changeProperties.extra.selectedCount Integer The number of students who have submitted their answers
      changeProperties.extra.correctCount Integer The number of students who have made the correct choice
      changeProperties.extra.averageAccuracy Float The rate at which the correct choice is made for this question
      changeProperties.extra.totalCount Integer The total number of students who have submitted their answers to this question
      cause String The reason for the property change
      operator Object The operator of the property change
      operator.userUuid String The ID of the operator
      operator.userName String The name of the operator
      operator.role String The role of the operator

    • After the teacher ends the quiz, the summarized data of the Pop-up Quiz widget updates. data contains the following fields:

      Field name Type Description
      action Integer The action type
      changeProperties Object The changed properties
      changeProperties.extra Object The extra information of the changed properties
      changeProperties.extra.selectedCount Integer The number of students who have submitted their answers
      changeProperties.extra.correctCount Integer The number of students who have made the correct choice
      changeProperties.extra.answerState Integer The status of this quiz:
      • 1 : In progress
      • 0: Ended
      changeProperties.extra.averageAccuracy Float The rate at which the correct choice is made for this question
      changeProperties.extra.totalCount Integer The total number of students who have submitted their answers to this question
      cause String The reason for the property change
      operator Object The operator of the property change
      operator.userUuid String The ID of the operator
      operator.userName String The name of the operator
      operator.role String The role of the operator

    Response example

    • After the teacher clicks the Start button to start a quiz, the summarized data of the Pop-up Quiz widget updates:

       "action": NumberInt("1"),
 "changeProperties": {
     "extra.correctItems": [
         "A",
         "B",
         "D"
     ],
     "extra.totalCount": NumberInt("1"),
     "extra.answerState": NumberInt("1"),
     "state": NumberInt("1"),
     "extra.popupQuizId": "ab5b183238a74d5a9c955dc87c6397e0",
     "extra.averageAccuracy": 0,
     "extra.correctCount": NumberInt("0"),
     "extra.items": [
         "A",
         "C",
         "B"
     ],
     "extra.receiveQuestionTime": NumberLong("1652413962895")
 },
 "operator": {
     "userName": "server",
     "userUuid": "server",
     "role": "server"
 }

    • After a student submits the answer, the student's data updates:

       "action": NumberInt("1"),
 "changeProperties": {
     "selectedItems": [
         "A",
         "B",
         "D"
     ],
     "isCorrect": true,
     "popupQuizId": "ab5b183238a74d5a9c955dc87c6397e0",
     "lastCommitTime": NumberLong("1652413989997")
 },
 "fromUser": {
     "userName": "yerongzhe2",
     "userUuid": "yerongzhe22",
     "role": "audience"
 }

    • After the teacher ends the quiz, the summarized data of the Pop-up Quiz widget updates:

       "action": NumberInt("1"),
 "changeProperties": {
     "extra.totalCount": NumberInt("1"),
     "extra.answerState": NumberInt("0"),
     "extra.selectedCount": NumberInt("1"),
     "extra.averageAccuracy": 1,
     "extra.correctCount": NumberInt("1")
 },
 "operator": {
     "userName": "server",
     "userUuid": "server",
     "role": "server"
 }

    Get data for polls

    Prototype

    • Method: GET
    • Request path: /edu/apps/{appId}/v2/rooms/{roomUuid}/widgets/polls/sequences

    Request parameters

    URL parameters

    Pass the following parameters in the URL:

    Parameter Type Description
    appId String (Required) Agora App ID.
    roomUuid String (Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 bytes.

    Query parameters

    Parameter Type Description
    nextId String (Optional) The starting ID of the next batch of data. When you call this method to get the data for the first time, leave this parameter empty or set it as null. Afterward, you can set this parameter as the nextId that you get in the response of the previous method call.
    count Integer (Optional) The number of pieces of data in this batch. The default value is 100.

    Response parameters

    The fields returned in data vary in different situations.

    • After the teacher clicks the Start button to start a poll, the summarized data of the Polling widget updates. data contains the following fields:

      Field name Type Description
      action Integer The action type
      changeProperties Object The changed properties
      changeProperties.extra Object The extra information of the changed properties
      changeProperties.extra.mode Integer The polling mode:
      • 1: Single-choice
      • 2: Multiple-choice
      changeProperties.extra.pollingState Integer The status of this poll:
      • 1 : In progress
      • 0: Ended
      changeProperties.extra.pollDetails Map<String, Object> The polling results. key is the option index, starting from 0.
      changeProperties.extra.pollDetails.num Integer The number of students who have selected this option
      changeProperties.extra.pollDetails.percentage Float The percentage of students who have selected this option in students who have submitted their choices
      changeProperties.extra.pollId String The poll ID
      changeProperties.extra.pollItems Object[] The option content
      changeProperties.state Integer The state of the Polling widget:
      • 0: Inactive
        • 1: Active
      cause String The reason for the property change
      operator Object The operator of the property change
      operator.userUuid String The ID of the operator
      operator.userName String The name of the operator
      operator.role String The role of the operator

    • After a student submits the choice, the student's data updates. data contains the following fields:

      Field name Type Description
      action Integer The action type
      changeProperties Object The changed properties
      changeProperties.extra Object The extra information of the changed properties
      changeProperties.extra.pollId String The poll ID
      changeProperties.extra.selectIndex Object[] The index of the option selected by this student
      cause String The reason for the property change
      operator Object The operator of the property change
      operator.userUuid String The ID of the operator
      operator.userName String The name of the operator
      operator.role String The role of the operator
      fromUser Object The user who starts this poll
      fromUser.userUuid String The ID of the user who starts this poll
      fromUser.userName String The name of the user who starts this poll
      fromUser.role String The role of the user who starts this poll

    • After a student submits the answer, the summarized data of the Polling widget updates. data contains the following fields:

      Field name Type Description
      action Integer The action type
      changeProperties Object The changed properties
      changeProperties.extra Object The extra information of the changed properties
      changeProperties.extra.pollDetails Map<String, Object> The polling results. key is the option index, starting from 0.
      changeProperties.extra.pollDetails.num Integer The number of students who have selected this option
      changeProperties.extra.pollDetails.percentage Float The percentage of students who have selected this option in students who have submitted their choices
      changeProperties.extra.pollId String The poll ID
      cause String The reason for the property change
      operator Object The operator of the property change
      operator.userUuid String The ID of the operator
      operator.userName String The name of the operator
      operator.role String The role of the operator

    • After the teacher ends the poll, the summarized data of the Polling widget updates. data contains the following fields:

      Field name Type Description
      action Integer The action type
      changeProperties Object The changed properties
      changeProperties.extra Object The extra information of the changed properties
      changeProperties.extra.pollingState Integer The status of this poll:
      • 1 : In progress
      • 0: Ended
      changeProperties.extra.pollDetails Map<String, Object> The polling results. key is the option index, starting from 0.
      changeProperties.extra.pollDetails.num Integer The number of students who have selected this option
      changeProperties.extra.pollDetails.percentage Float The percentage of students who have selected this option in students who have submitted their choices
      changeProperties.extra.pollId String The poll ID
      cause String The reason for the property change
      operator Object The operator of the property change
      operator.userUuid String The ID of the operator
      operator.userName String The name of the operator
      operator.role String The role of the operator

    Response example

    • After the teacher clicks the Start button to start a poll, the summarized data of the Polling widget updates:

       "action": NumberInt("1"),
 "changeProperties": {
     "extra.pollId": "e556ce3df5cd4c23941b03bf54d29ba3",
     "extra.pollState": NumberInt("1"),
     "extra.pollItems": [
         "aaa",
         "bbb",
         "ccc",
         "ddd",
         "eee"
     ],
     "extra.mode": NumberInt("2"),
     "state": NumberInt("1"),
     "extra.pollDetails": {
         "0": {
             "num": NumberInt("0"),
             "percentage": 0
         },
         "1": {
             "num": NumberInt("0"),
             "percentage": 0
         },
         "2": {
             "num": NumberInt("0"),
             "percentage": 0
         },
         "3": {
             "num": NumberInt("0"),
             "percentage": 0
         },
         "4": {
             "num": NumberInt("0"),
             "percentage": 0
         }
     }
 },
 "operator": {
     "userName": "server",
     "userUuid": "server",
     "role": "server"
 }

    • After a student submits the choice, the student's data updates:

       "action": NumberInt("1"),
 "changeProperties": {
     "pollId": "e556ce3df5cd4c23941b03bf54d29ba3",
     "selectIndex": [
         NumberInt("1"),
         NumberInt("2"),
         NumberInt("4")
     ]
 },
 "fromUser": {
     "userName": "yerongzhe2",
     "userUuid": "yerongzhe22",
     "role": "audience"
 },
 "operator": {
     "userName": "server",
     "userUuid": "server",
     "role": "server"
 }

    • After a student submits the choice, the summarized data of the Polling widget updates:

       "action": NumberInt("1"),
 "changeProperties": {
     "extra.pollId": "2f38e6de32064713adf135de41c963df",
     "extra.pollDetails": {
         "0": {
             "num": NumberInt("1"),
             "percentage": 0.33333334
         },
         "1": {
             "num": NumberInt("3"),
             "percentage": 1
         },
         "2": {
             "num": NumberInt("3"),
             "percentage": 1
         },
         "3": {
             "num": NumberInt("0"),
             "percentage": 0
         },
         "4": {
             "num": NumberInt("2"),
             "percentage": 0.6666667
         }
     }
 },
 "operator": {
     "userName": "server",
     "userUuid": "server",
     "role": "server"
 }

    • After the teacher ends the poll, the summarized data of the Polling widget updates:

       "action": NumberInt("1"),
 "changeProperties": {
     "extra.pollId": "2f38e6de32064713adf135de41c963df",
     "extra.pollDetails": {
         "0": {
             "num": NumberInt("1"),
             "percentage": 0.33333334
         },
         "1": {
             "num": NumberInt("3"),
             "percentage": 1
         },
         "2": {
             "num": NumberInt("3"),
             "percentage": 1
         },
         "3": {
             "num": NumberInt("0"),
             "percentage": 0
         },
         "4": {
             "num": NumberInt("2"),
             "percentage": 0.6666667
         }
     }
 },
 "operator": {
     "userName": "server",
     "userUuid": "server",
     "role": "server"
 }

    Status code

    Response status code Business status code Description
    200 0 The request succeeds.
    400 400 The request parameter is incorrect.
    401 N/A Possible reasons:
  • The App ID is invalid.
  • Unauthorized. Incorrect x-agora-uid or x-agora-token.
    		•
    403 30403200 The classroom is muted globally. Users cannot send chat messages.
    404 N/A The server cannot find the requested resource.
    404 20404100 The classroom does not exist.
    404 20404200 The user does not exist.
    409 30409410 The recording has not been started.
    409 30409411 The recording has not been ended.
    409 30409100 The class has been started.
    409 30409101 The class has been ended.
    500 500 The server has an internal error and cannot process the request.
    503 N/A Internal server error. The gateway or proxy server does not receive a timely response from the upstream server.