Flexible Classroom Cloud Service RESTful API Reference

Documentation





Flexible Classroom

Agora.io Community





Flexible Classroom Cloud Service RESTful API Reference

Last updated 2021/06/15 12:22:52

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.

Set the classroom state

Description

Call this method to set the classroom state: Not started, Started, Ended.

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) The Agora App ID, see Get the 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`: Start recording. `2`: Ended.

Request example

// Set the state of the test_class as started
https://api.agora.io/na/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
}

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) The Agora App ID, see Get the 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

// Kick the user with the ID 123 out of test_class
https://api.agora.io/na/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 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) The Agora App ID, see Get the 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`: Start recording.

Request body parameters

Pass in the following parameters in the request body.

Parameter	Type	Description
`mode`	String	(Optional) The recording mode: Set `mode` 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 webpage 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. `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: 1280 × 720: The default value is 1130. 960 × 720: The default value is 910. 848 × 480: The default value is 610. 640 × 480: The default value is 400. For all other resolutions, the default value is 300. `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], and the default value is 24. If the limit set by `maxRecordingHour` is exceeded, the recording stops automatically.

Request example

Request URL

// Start recording test_class
https://api.agora.io/na/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}"
    }
}

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) The Agora App ID, see Get the 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

// Get the recording list in test_class
https://api.agora.io/na/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 this public resources.

Prototype

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

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) The Agora App ID, see Get the 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

// Upload a public resource with the ID of class_file_1 to test_class
https://api.agora.io/na/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) The Agora App ID, see Get the 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
`resourceUuid`	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/na/edu/apps/{your_app_Id}/v1/rooms/test_class/resources

Request Body

{
    "resourceUuid": ["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) The Agora App ID, see Get the 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

// Get the public resource with the ID of class_file_1 in test_class
https://api.agora.io/na/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) The Agora App ID, see Get the 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

// Get the event of classroom state update in test_class
https://api.agora.io/na/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. See Flexible Classroom 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. See Flexible Classroom 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) The Agora App ID, see Get the Agora App ID.

Request example

https://api.agora.io/na/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. See Flexible Classroom 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. See Flexible Classroom Events.

Response example

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

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.

Is this page helpful?

Yes