Flexible Classroom Cloud Service RESTful API Reference

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.

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.

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
}

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.