# Classroom REST API (/en/api-reference/api-ref/flexible-classroom/classroom-rest-api)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
This page provides detailed help for the Flexible Classroom RESTful APIs.
## Basic information [#basic-information]
### Server [#server]
All requests are sent to the host `api.agora.io`. See [Ensure service reliability](#ensure-service-reliability) for alternate domain names.
### Data format [#data-format]
The Content-Type of all requests is `application/json`.
### Authentication [#authentication]
Flexible Classroom Cloud Service uses tokens for authentication. You need to put the corresponding information into the `Authorization: agora token=` field when sending your HTTP request. For details, see [Secure authentication with tokens](/en/realtime-media/flexible-classroom/build/set-up-your-account-and-authentication/authentication-workflow).
## Classroom-related [#classroom-related]
### Create a classroom [#create-a-classroom]
#### Description [#description]
Call this method to create a classroom. After it is created, the classroom is reserved for five days.
#### Prototype [#prototype]
* Method: POST
* Endpoint: `/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}`
#### Request parameters [#request-parameters]
**URL parameters**
Pass the following parameters in the URL:
| Parameter | Type | Description |
| :--------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region` | String | (Required) The region for connection. 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 characters. The following characters are supported:- All lowercase English letters: a to z.
- All uppercase English letters: A to Z.
- The numbers 0 to 9.
- The space character.
- The following special characters: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "\<", "=", ".", ">", "?", "@", "\[", "]", "^", "\_", "\{", "}", "\|", "\~", "," |
**Request body parameters**
Pass in the following parameters in the request body:
| Parameter | Type | Description |
| :--------------------------------------------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `roomType` | String | (Required) The type of the classroom. You can set the value to :- `0`: One-to-one classroom.
- `2`: Lecture hall.
- `4`: Small classroom.
- `10`: Small cloud classroom.Once set, this parameter value cannot be changed. |
| `roomName` | String | (Required) The name of the classroom. The maximum length of this parameter is 64 characters. |
| `roomProperties` | Object | (Optional) The properties of the classroom. It includes the name of the room, room number whiteboard plug-in configuration, chat plug-in configuration, room opening, end time, duration, configuration of the number of people who raise their hands to connect to the microphone, the maximum number of people to connect to the microphone, and the switch status configuration of the device for students to join the room by default, etc. |
| `roomProperties.schedule` | Object | (Optional) The schedule of the classroom. |
| `roomProperties.schedule.startTime` | Integer | (Optional) The start timestamp (ms) of the class. Once set, this parameter value cannot be changed. |
| `roomProperties.schedule.duration` | Integer | (Optional) The duration of the class, in seconds. The maximum value is 86,400 seconds, and it is recommended to set it according to the actual duration of the class. If you set the class duration and dragging duration, when recording is turned on, the maximum recording time `maxRecordingHour` parameter will be set based on the sum of the two and rounded up. See [Set the recording state](#set-the-recording-state). |
| `roomProperties.schedule.closeDelay` | Integer | (Optional) The delay of the class end time, in seconds. When the class duration ends, the class will enter the "End" state (state= 2). At this time, users can still enter and stay in the classroom normally. When the dragging time ends, the class will enter the "closed" state (state= 3) and all users will be kicked out. |
| `roomProperties.processes` | Object | (Optional) The process of inviting students to go "on the stage". |
| `roomProperties.processes.handsUp` | Object | (Optional) The settings of "on the stage". |
| `roomProperties.processes.handsUp.maxAccept` | Integer | (Optional) The maximum number of students "on the stage". |
| `roomProperties.processes.handsUp.defaultAcceptRole` | String | (Optional) The default user on the stage. If you hope to set the student on the stage, set it as "audience". If not, set it as "" or do not set this parameter. In the cloud classroom use-case, default is "". |
| `roomProperties.flexProps` | Object | (Optional) The initial properties of the classroom. The user's backend can pass customized parameters to the room through this parameter. Users can set custom attributes for any classroom based on their own business needs. Flexible Classroom will synchronize changes in this attribute to all clients in the classroom to realize your own business expansion. |
| `roomProperties.widgets` | Object | (Optional) Settings of the widgets in the classroom. |
| `roomProperties.widgets.netlessBoard` | Object | (Optional) Settings of the whiteboard widget in the classroom. |
| `roomProperties.widgets.netlessBoard.state` | Integer | (Optional) The state of the whiteboard widget in the classroom:- `0`: Disabled.
- `1`: Enabled. |
| `roomProperties.widgets.easemobIM` | Object | (Optional) Settings of the chat widget in the classroom. |
| `roomProperties.widgets.easemobIM.state` | Integer | (Optional) The state of the chat widget in the classroom:- `0`: Disabled.
- `1`: Enabled. |
| `roleConfig` | Object | (Optional) The role configuration. |
| `roleConfig.2` | Object | (Optional) The configuration of the student role. |
| `roleConfig.2.limit` | Integer | (Optional) The limit of the number of students. |
| `roleConfig.2.defaultStream` | Object | (Optional) The default stream type of the student. |
| `roleConfig.2.defaultStream.state` | Integer | (Optional) The state of the default stream type of the student:- `0`: Disabled.
- `1`: Enabled. |
| `roleConfig.2.defaultStream.videoState` | Integer | (Optional) The video state of the default stream of the student:- `0`: Disabled.
- `1`: Enabled. |
| `roleConfig.2.defaultStream.audioState` | Integer | (Optional) The audio state of the default stream of the student:- `0`: Disabled.
- `1`: Enabled. |
To create a small cloud classroom, the following are the required parameters:
```json
{
...
"roomName":"{roomName}",
"roomType":10,
"roleConfig":{
"2":{
"defaultStream":{
"audioState":1,
"state":1,
"videoState":1
},
"limit":49
}
},
...
}
```
#### Request example [#request-example]
```bash
curl -X POST 'https://api.agora.io/{region}/edu/apps/{YourAppId}/v2/rooms/test_room' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"roomName": "test_class",
"roomType": 4,
"roleConfig": { // The audio and video permissions of students joining the room are turned on or off by default.（Optional）
"2": {
"limit": 50,
"defaultStream": {
"state": 1,
"videoState": 1,
"audioState": 1
}
}
},
"roomProperties": {
"schedule": {
"startTime": 1655452800000,
"duration": 600,
"closeDelay": 300
},
"processes": {
"handsUp": {
"maxAccept": 10, //The maximum number of students "on the stage".
"defaultAcceptRole": "" //(Optional) The default user on the stage. If you hope to set the student on the stage, set it as "audience". If not, set is as "" or do not set this parameter.In cloud classroom Scenario default is ""
}
},
//The user's backend can pass customized parameters to the room through this parameter.Users can set custom attributes for any classroom based on their own business needs. Flexible Classroom will synchronize changes in this attribute to all clients in the classroom to realize your own business expansion.
"flexProps": {
"exampleKey": "exampleValue"
},
"widgets": {//The state of the widgets in the classroom : on or off
"netlessBoard": {
"state": 0
},
"easemobIM": {
"state": 1
}
}
}
}'
```
#### Response parameters [#response-parameters]
| Parameter | Type | Description |
| :-------- | :------ | :---------------------------------------------------------------------------- |
| `code` | Integer | Request status code:- 0: The request succeeds.
- Non-zero: The request fails. |
| `msg` | String | Detailed information about the code. |
| `ts` | Number | The current Unix timestamp (in milliseconds) of the server in UTC. |
#### Response example [#response-example]
```json
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
```
Note that you can just call the API to create a room, the server will respond with the `200` or `409`. `200` means the room is created, `409` means the room has already been created and you can join the classroom.
### Query a classroom [#query-a-classroom]
#### Description [#description-1]
Returns all information about the room object.
#### Prototype [#prototype-1]
* Method: GET
* Endpoint: `{region}/edu/apps/{appId}/v2/rooms/{roomUuid}`
#### Request parameters [#request-parameters-1]
**URL parameters**
Pass the following parameters in the URL:
| Parameter | Type | Description |
| :--------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region` | String | (Required) The region for connection. 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 characters. The following characters are supported:- All lowercase English letters: a to z.
- All uppercase English letters: A to Z.
- The numbers 0 to 9.
- The space character.
- The following special characters: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "\<", "=", ".", ">", "?", "@", "\[", "]", "^", "\_", "\{", "}", "\|", "\~", "," |
#### Request example [#request-example-1]
```bash
curl -X GET 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
```
#### Response parameters [#response-parameters-1]
| Parameter | Type | Description |
| :-------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code` | Integer | Request status code:- 0: The request succeeds.
- Non-zero: The request fails. |
| `msg` | String | Detailed information about the code. |
| `ts` | Number | The current Unix timestamp (in milliseconds) of the server in UTC. |
| `data` | Object | The returned object, which contains the following data:- `roomUuid`: String, room ID.
- `roomName`: String, room name.
- `createTime`: Integer, room creation timestamp.
- `roomProperties`: Object, room attributes.
* `roomType`: Integer, room type.
* `0`: 1 to 1.
* `2`: Large classroom.
* `4`: Small classroom.
* `10`: Small cloud classroom.
* `schedule`: Object, lesson plan.
* `state`: Integer, room state.
* `0`: Not started.
* `1`: Started.
* `2`: Ended.
* `3`: Closed.
* `startTime`: Integer, starting time.
* `endTime`: Integer, end time.
* `closeTime`: Integer, closing time.
* `widgets`: Object, component collection.
* `netlessBoard`: Object, whiteboard component.
* `extra`: Object, extended information.
* `boardAppId`: String, whiteboard App ID.
* `boardId`: String, whiteboard room ID.
* `boardToken`: String, whiteboard room Token.
* `boardRegion`: String, whiteboard area.
* `state`: Integer, component state.
* `0`: Integer, not activated.
* `1`: Integer, activated.
* `easemobIM`: Object, chat room component.
* `extra`: Object, extended information.
* `orgName`: String, organization name.
* `appName`: String, app name.
* `chatRoomId`: String, chat room ID.
* `appKey`: String, app Key.
* `state`: Integer, component state.
* 0: Integer, not activated.
* 1: Integer, activated. |
#### Response example [#response-example-1]
```json
{
"msg": "Success",
"code": 0,
"ts": 1684231543281,
"data": {
"roomName": "jasoncai's Room",
"roomUuid": "3579768dd1e1eec8522d3ed76992afd04",
"scenario": "education",
"roleConfig": {
...
},
"roomProperties": {
"reward": {
...
},
"processes": {
"handsUp": {
...
},
"openCamera": {
...
},
"remoteControl": {
...
},
"waveArm": {
...
}
},
"im": {
"huanxin": {
...
}
},
"screen": {
...
},
"groups": {
...
},
"carousel": {
...
},
"widgets": {
"netlessBoard": {
"extra": {
...
},
"state": 1
},
"easemobIM": {
"extra": {
...
}
}
},
"schedule": {
"closeDelay": 600,
"duration": 1800
},
"webhookConfig": {
...
},
"record": {
...
},
"state": 0,
"board": {
"info": {
...
}
},
"roomType": 4
},
"roomTemplate": "edu_medium_v1",
"muteChat": {},
"muteVideo": {},
"muteAudio": {},
"state": 0,
"checkState": false,
"createTime": 1683884683422
}
}
```
### Set the classroom state [#set-the-classroom-state]
#### Description [#description-2]
Call this method to set the classroom state: Not started, Started, Ended.
#### Prototype [#prototype-2]
* Method: PUT
* Endpoint: `/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/states/{state}`
#### Request parameters [#request-parameters-2]
**URL parameters**
Pass the following parameter in the URL.
| Parameter | Type | Description |
| :--------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region` | String | (Required) The region for connection. For details, see [Network geofencing](/en/realtime-media/flexible-classroom/build/secure-your-classrooms/classroom-security#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 a channel. The string length must be less than 64 characters. The following character sets are supported:- All lowercase English letters: a to z
- All uppercase English letters: A to Z
- All numeric characters: 0-9
- The space character
- "!", 1"#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "\<", "=", ".", ">", "?", "@", "\[", "]", "^", "\_", "\{", "}", "\|", "\~", "," |
| `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 [#request-example-2]
```bash
curl -X PUT 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/states/1' \
-H 'Authorization: agora token={educationToken}' \
```
#### Response parameters [#response-parameters-2]
| 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 [#response-example-2]
```json
"status": 200,
"body":
{
"code": 0,
"msg": "Success",
"ts": 1610450153520
}
```
### Update custom classroom properties [#update-custom-classroom-properties]
#### Description [#description-3]
Add or update the custom properties of a specified classroom.
#### Prototype [#prototype-3]
* Method: PUT
* Endpoint: `/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/properties`
#### Request parameters [#request-parameters-3]
**URL parameters**
Pass the following parameters in the URL:
| Parameter | Type | Description |
| :--------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region` | String | (Required) The region for connection. For details, see [Network geofencing](/en/realtime-media/flexible-classroom/build/secure-your-classrooms/classroom-security#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 a channel. The string length must be less than 64 characters. The following character sets are supported:- All lowercase 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. |
| `roomProperties.examinationUrl` | String | (Optional) The URL of the exam papers used in proctoring exam use-cases. |
| `cause` | Object | The update reason. |
#### Request example [#request-example-3]
```bash
curl -X PUT 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/properties' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"properties": {
"key1": "value1",
"key2": "value2"
},
"cause": {}
}'
```
#### Response parameters [#response-parameters-3]
| 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 [#response-example-3]
```json
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
```
### Delete custom classroom properties [#delete-custom-classroom-properties]
#### Description [#description-4]
Delete the custom properties of a specified classroom.
#### Prototype [#prototype-4]
* Method: DELETE
* Endpoint: `/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/properties`
#### Request parameters [#request-parameters-4]
**URL parameters**
Pass the following parameters in the URL:
| Parameter | Type | Description |
| :--------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region` | String | (Required) The region for connection. For details, see [Network geofencing](/en/realtime-media/flexible-classroom/build/secure-your-classrooms/classroom-security#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 a channel. The string length must be less than 64 characters. The following character sets are supported:- All lowercase 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-example-4]
**Request Body**
```bash
curl -X DELETE 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/properties' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"properties": ["key1", "key2"],
"cause": {}
}'
```
#### Response parameters [#response-parameters-4]
| 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 [#response-example-4]
```json
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
```
### Create or remove breakout classrooms [#create-or-remove-breakout-classrooms]
#### Description [#description-5]
Create or remove breakout rooms. Breakout rooms are sessions that are split off from a classroom that allow students to discuss classwork in smaller groups.
#### Prototype [#prototype-5]
* Method: PUT
* Endpoint: `/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/groups/states/{state}`
#### Request parameters [#request-parameters-5]
**URL parameters**
Pass the following parameters in the URL:
| Parameter | Type | Description |
| :--------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region` | String | (Required) The region for connection. For details, see [Network geofencing](/en/realtime-media/flexible-classroom/build/secure-your-classrooms/classroom-security#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. |
| `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 a channel. The string length must be less than 64 characters. The following character sets are supported:- All lowercase English letters: a to z.
- All numeric characters: 0-9
- The space character.
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "\<", "=", ".", ">", "?", "@", "\[", "]", "^", "\_", "\{", "}", "\|", "\~", "," |
| `state` | Integer | Whether to enable breakout rooms:- `1`: Enabled. Set as this value if you want to create breakout rooms.
- `0`: Disabled. Set as this value if you want to remove breakout rooms. |
**Request body parameters**
* To create breakout rooms, you need to set `state` to `1` and pass in the following parameters in the request body.
* To remove all breakout rooms, you need to set `state` to `0` and leave the request body blank.
| Parameter | Type | Description |
| :-------- | :---- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `groups` | Array | (Required) The breakout rooms to be created. This parameter consists of the following parameters:* `groupUuid`: (Optional) The ID of the breakout room, string type. If you do not provide an ID, an ID is automatically assigned to the breakout room.
* `groupName`: (Optional) The name of the breakout room, string type.
* `users`: (Required) The user list in the breakout room, array type. This parameter consists of the following parameters:
* `userUuid`: (Required) The user ID. This is the unique identifier of the user when logging in to Signaling. The string length must be less than 64 characters. |
#### Request example [#request-example-5]
```bash
curl -X PUT 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/states/1' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"groups":[
{
"groupUuid": "group1",
"groupName":"Group 01",
"users":[{
"userUuid": "user1"
}]
}
]
}'
```
#### Response parameters [#response-parameters-5]
| 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 [#response-example-5]
```json
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
```
## Recording-related [#recording-related]
### Set the recording state [#set-the-recording-state]
#### Description [#description-6]
Call this method to start or stop recording a specified classroom.
#### Prototype [#prototype-6]
* Method: PUT
* Endpoint: `/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/records/states/{state}`
#### Request parameters [#request-parameters-6]
**URL parameters**
Pass the following parameter in the URL.
| Parameter | Type | Description |
| :--------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region` | String | (Required) The region for connection. For details, see [Network geofencing](/en/realtime-media/flexible-classroom/build/secure-your-classrooms/classroom-security#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 a channel. The string length must be less than 64 characters. The following character sets are supported:- All lowercase English letters: a to z.
- All numeric characters: 0-9
- The space character.
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "\<", "=", ".", ">", "?", "@", "\[", "]", "^", "\_", "\{", "}", "\|", "\~", "," |
| `state` | Integer | (Required) The recording state:- `0`: Stop recording.
- `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:- `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`.
- `publishRtmp`: (Optional) Whether to push the recorded webpage to CDN:
* `true`: Yes.
* `false`: No.
- `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-example-6]
```bash
curl -X PUT 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/records/states/1' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"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",
"publishRtmp": "true"
},
"retryTimeout": 60
}'
```
#### Response parameters [#response-parameters-6]
| 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 | The returned object, which contains the following data:- `recordId`: String. The unique identifier of the recording.
- `sid`: String. The `sid` of cloud recording.
- `resourceId`: String. The `resourceId` of cloud recording.
- `state`: Integer. The recording state: `0`: The recording ends. `1`: The recording begins.
- `startTime`: Integer. The timestamp (ms) when the recording begins.
- `streamingUrl`: Object. The URL address of pulling the CDN stream: `rtmp`: String. The URL of the RTMP streaming. `flv`: String. The URL of the FLV streaming. `hls`: String. The URL of the HLS streaming. |
#### Response example [#response-example-6]
```json
"status": 200,
"body":
{
"code": 0,
"ts": 1610450153520,
"streamingUrl": {
"rtmp": "",
"flv": "",
"hls": ""
}
}
```
### Update the recording configurations [#update-the-recording-configurations]
#### Description [#description-7]
Call this method during the recording to update the recording configurations. Every time this method is called, the previous configurations are overwritten.
#### Prototype [#prototype-7]
* Method: PATCH
* Endpoint: `/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/records/states/{state}`
#### Request parameters [#request-parameters-7]
**URL parameters**
Pass the following parameter in the URL.
| Parameter | Type | Description |
| :--------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region` | String | (Required) The region for connection. For details, see [Network geofencing](/en/realtime-media/flexible-classroom/build/secure-your-classrooms/classroom-security#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 a channel. The string length must be less than 64 characters. The following character sets are supported:- All lowercase 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-example-7]
```bash
curl -X PATCH 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/records/states/1' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"webRecordConfig": {
"onhold": false
}
}'
```
#### Response parameters [#response-parameters-7]
| 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 [#response-example-7]
```json
"status": 200,
"body":
{
"code": 0,
"ts": 1610450153520
}
```
### Get the recording list [#get-the-recording-list]
#### Description [#description-8]
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 [#prototype-8]
* Method: GET
* Endpoint: `/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/records`
#### Request parameters [#request-parameters-8]
**URL parameters**
Pass the following parameter in the URL.
| Parameter | Type | Description |
| :--------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region` | String | (Required) The region for connection. For details, see [Network geofencing](/en/realtime-media/flexible-classroom/build/secure-your-classrooms/classroom-security#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 a channel. The string length must be less than 64 characters. The following character sets are supported:- All lowercase 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 [#request-example-8]
```bash
curl -X PATCH 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/records/states/1' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"webRecordConfig": {
"onhold": false
}
}'
```
#### Response parameters [#response-parameters-8]
| 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 a 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:
* `3`: Web Page 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.
* `unready`: Boolean. `true` means that recording fails.
- `webRecordingUrlQuery`: String. Same as `query` in webpage recording. |
#### Response example [#response-example-8]
```json
{
"msg":"Success",
"code":0,
"ts":1706091167911,
"data":{
"total":1,
"list":[
{
"recordId":"sssssssssss",
"appId":"sssssssssss",
"roomUuid":"sssssssssss",
"startTime":1706079930586,
"endTime":1706081355989,
"resourceId":"443322222",
"sid":"sssssssssss",
"recordUid":"sssssssssss",
"type":3,
"status":2,
"url":"https://xxxxxxxx.m3u8",
"recordDetails":[
{
"url":"xxxxxxxxx.mp4"
}
],
"webRecordUrlQuery":"xxxxxxx"
}
],
"count":1
}
}
```
## User-related [#user-related]
### Query a specific user [#query-a-specific-user]
#### Prototype [#prototype-9]
* Method: GET
* Endpoint: `/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/users/{userUuid}`
#### Request parameters [#request-parameters-9]
**URL parameters**
Pass the following parameter in the URL.
| Parameter | Type | Description |
| :--------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region` | String | (Required) The region for connection. For details, see [Network geofencing](/en/realtime-media/flexible-classroom/build/secure-your-classrooms/classroom-security#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 characters. The following characters are supported:- All lowercase English letters: a to z.
- All uppercase English letters: A to Z.
- The numbers 0 to 9.
- The space character.
- The following special characters: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "\<", "=", ".", ">", "?", "@", "\[", "]", "^", "\_", "\{", "}", "\|", "\~", "," |
| `userUuid` | String | (Required) The user ID. This is the unique identifier of the user and also the user ID used when logging in to Signaling. The string length must be less than 64 characters. Supported character scopes are:- All lowercase English letters: a to z.All numeric characters.- 0-9
- The space character.
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "\<", "=", ".", ">", "?", "@", "\[", "]", "^", "\_", "\{", "}", "\|", "\~", "," |
#### Request example [#request-example-9]
```bash
curl -X GET 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/users/test_user' \
-H 'Authorization: agora token={educationToken}' \
```
#### Response parameters [#response-parameters-9]
| Parameter | Type | Description |
| :-------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code` | Integer | Business status code:- 0: The request succeeds.
- Non-zero: The request fails. |
| `msg` | String | The detailed information. |
| `data` | Object | Include the following parameters:- `userUuid`: String, the user ID.
- `userName`: String, the user name.
- `role`: Integer. The user role. This parameter can be set as one of the following values:
* `1`: Teacher.
* `2`: Student.
* `3`: Teaching assistant.
- `streamUuid`: String. The ID of the stream, which is also the uid used when joining an RTC SDK channel.
- `state`: Whether the user is online:
* `0`: Offline.
* `1`: Online.
- `userProperties`: Object. The user property.
- `updateTime`: Number. The time when the user status is updated, Unix timestamp (in milliseconds), UTC time. |
#### Response example [#response-example-9]
```json
{
"msg": "Success",
"code": 0,
"ts": 1658126805245,
"data": {
"userName": "jasoncai",
"userUuid": "681d9aca4924e9a84ad301e8cca438a71",
"role": "1",
"userProperties": {},
"updateTime": 1658126782174,
"streamUuid": "1417753684",
"state": 1
}
}
```
### Update custom user properties [#update-custom-user-properties]
#### Description [#description-9]
Add or update the custom properties of a specified user.
#### Prototype [#prototype-10]
* Method: PUT
* Endpoint: `/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/users/{userUuid}/properties`
#### Request parameters [#request-parameters-10]
**URL parameters**
Pass the following parameters in the URL:
| Parameter | Type | Description |
| :--------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region` | String | (Required) The region for connection. For details, see [Network geofencing](/en/realtime-media/flexible-classroom/build/secure-your-classrooms/classroom-security#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 a channel. The string length must be less than 64 characters. The following character sets are supported:- All lowercase 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 when logging in to Signaling. The string length must be less than 64 characters. The following character sets are supported:- All lowercase 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-example-10]
```bash
curl -X PUT 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/users/test_user/properties' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"properties": {
"key1": "value1",
"key2": "value2"
},
"cause": {}
}'
```
#### Response parameters [#response-parameters-10]
| 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 [#response-example-10]
```json
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
```
### Delete custom user properties [#delete-custom-user-properties]
#### Description [#description-10]
Delete the custom properties of a specified user.
#### Prototype [#prototype-11]
* Method: DELETE
* Endpoint: `/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/users/{userUuid}/properties`
#### Request parameters [#request-parameters-11]
**URL parameters**
Pass the following parameters in the URL:
| Parameter | Type | Description |
| :--------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region` | String | (Required) The region for connection. For details, see [Network geofencing](/en/realtime-media/flexible-classroom/build/secure-your-classrooms/classroom-security#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 a channel. The string length must be less than 64 characters. The following character sets are supported:- All lowercase 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 when logging in to Signaling. The string length must be less than 64 characters. The following character sets are supported:- All lowercase 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-example-11]
```bash
curl -X DELETE 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/users/test_user/properties' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"properties": ["key1", "key2"],
"cause": {}
}'
```
#### Response parameters [#response-parameters-11]
| 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 [#response-example-11]
```json
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
```
### Kick a user out of a classroom [#kick-a-user-out-of-a-classroom]
#### Description [#description-11]
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 [#prototype-12]
* Method: POST
* Endpoint: `/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/users/{userUuid}/exit`
#### Request parameters [#request-parameters-12]
**URL parameters**
Pass the following parameters in the URL:
| Parameter | Type | Description |
| :--------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region` | String | (Required) The region for connection. For details, see [Network geofencing](/en/realtime-media/flexible-classroom/build/secure-your-classrooms/classroom-security#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 a channel. The string length must be less than 64 characters. The following character sets are supported:- All lowercase 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 when logging in to Signaling. The string length must be less than 64 characters. The following character sets are supported:- All lowercase 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-example-12]
```bash
curl -X POST 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/users/test_user/exit' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"dirty": {
"state": 1,
"duration": 600
}
}'
```
#### Response parameters [#response-parameters-12]
| 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 [#response-example-12]
```json
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
```
## Classroom event-related [#classroom-event-related]
### Query a specified event [#query-a-specified-event]
#### Description [#description-12]
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 [#prototype-13]
* Method: GET
* Endpoint: `/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/sequences`
#### Request parameters [#request-parameters-13]
**URL parameters**
Pass the following parameters in the URL:
| Parameter | Type | Description |
| :--------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region` | String | (Required) The region for connection. For details, see [Network geofencing](/en/realtime-media/flexible-classroom/build/secure-your-classrooms/classroom-security#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 a channel. The string length must be less than 64 characters. The following character sets are supported:- All lowercase 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](#events). |
#### Request example [#request-example-13]
```bash
curl -X GET 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/sequences?cmd=20' \
-H 'Authorization: agora token={educationToken}' \
```
#### Response parameters [#response-parameters-13]
| 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:
- `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 [#response-example-13]
```json
{
"msg": "Success",
"code": 0,
"ts": 1610433913533,
"data": {
"total": 1,
"list": [
{
"roomUuid": "",
"cmd": 20,
"sequence": 1,
"version": 1,
"data": {}
}
],
"nextId": null,
"count": 1
}
}
```
### Get all classroom events [#get-all-classroom-events]
#### Description [#description-13]
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.
* You cannot get events one hour after a classroom is destroyed.
#### Prototype [#prototype-14]
* Method: GET
* Endpoint: `/{region}/edu/polling/apps/{appId}/v2/rooms/sequences`
#### Request parameters [#request-parameters-14]
**URL parameters**
Pass the following parameter in the URL.
| Parameter | Type | Description |
| :-------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region` | String | (Required) The region for connection. For details, see [Network geofencing](/en/realtime-media/flexible-classroom/build/secure-your-classrooms/classroom-security#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 [#request-example-14]
```bash
curl -X GET 'https://api.sd-rtn.com/{region}/edu/polling/apps/{yourAppId}/v2/rooms/sequences' \
-H 'Authorization: agora token={educationToken}' \
```
#### Response parameters [#response-parameters-14]
| 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](#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](#events). |
#### Response example [#response-example-14]
```json
"status": 200,
"body":
{
"msg": "Success",
"code": 0,
"ts": 1610167740309,
"data":[
{
"roomUuid": "xxxxxx",
"cmd": 20,
"sequence": 1,
"version": 1,
"data":{}
}
]
}
```
### Get data for pop-up quizzes [#get-data-for-pop-up-quizzes]
#### Prototype [#prototype-15]
* Method: GET
* Request path: `/edu/apps/{appId}/v2/rooms/{roomUUid}/widgets/popupQuiz/sequences`
#### Request parameters [#request-parameters-15]
**URL parameters**
Pass the following parameters in the URL:
| Parameter | Type | Description |
| :--------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region` | String | (Required) The region for connection. For details, see [Network geofencing](/en/realtime-media/flexible-classroom/build/secure-your-classrooms/classroom-security#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 a channel. The string length must be less than 64 characters. |
**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. |
#### Request example [#request-example-15]
```bash
curl -X GET 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/widgets/popupQuiz/sequences' \
-H 'Authorization: agora token={educationToken}' \
```
#### Response parameters [#response-parameters-15]
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 |
| widgetUuid | String | The widget ID |
| 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 |
| cause.popQuizId | String | The Pop-up Quiz ID |
| cause.action | Integer | The action type:- `1`: The teacher starts taking the quiz
- `2`: The teacher finishes taking the quiz
- `3`: The student hands over the answer
- `4`: The information is updated |
| 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 |
| widgetUuid | String | The widget ID |
| 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 |
| cause.popQuizId | String | The Pop-up Quiz ID |
| cause.action | Integer | The action type:- `1`: The teacher starts taking the quiz
- `2`: The teacher finishes taking the quiz
- `3`: The student hands over the answer
- `4`: The information is updated |
| 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 |
| widgetUuid | String | The widget ID |
| 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 |
| cause.popQuizId | String | The Pop-up Quiz ID |
| cause.action | Integer | The action type:- `1`: The teacher starts taking the quiz
- `2`: The teacher finishes taking the quiz
- `3`: The student hands over the answer
- `4`: The information is updated |
| 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 |
| widgetUuid | String | The widget ID |
| 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 |
| cause.popQuizId | String | The Pop-up Quiz ID |
| cause.action | Integer | The action type:- `1`: The teacher starts taking the quiz
- `2`: The teacher finishes taking the quiz
- `3`: The student hands over the answer
- `4`: The information is updated |
| 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 [#response-example-15]
* After the teacher clicks the Start button to start a quiz, the summarized data of the Pop-up Quiz widget updates:
```json
"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:
```json
"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:
```json
"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 [#get-data-for-polls]
#### Prototype [#prototype-16]
* Method: GET
* Request path: `/edu/apps/{appId}/v2/rooms/{roomUUid}/widgets/poll/sequences`
#### Request parameters [#request-parameters-16]
**URL parameters**
Pass the following parameters in the URL:
| Parameter | Type | Description |
| :--------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region` | String | (Required) The region for connection. For details, see [Network geofencing](/en/realtime-media/flexible-classroom/build/secure-your-classrooms/classroom-security#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 a channel. The string length must be less than 64 characters. |
**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. |
#### Request example [#request-example-16]
```bash
curl -X GET 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/widgets/popupQuiz/sequences' \
-H 'Authorization: agora token={educationToken}' \
```
#### Response parameters [#response-parameters-16]
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 |
| widgetUuid | String | The widget ID |
| 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\ | 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 |
| cause.popQuizId | String | The Pop-up Quiz ID |
| cause.action | Integer | The action type:- `1`: The teacher starts taking the quiz
- `2`: The teacher finishes taking the quiz
- `3`: The student hands over the answer
- `4`: The information is updated |
| 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 |
| widgetUuid | String | The widget ID |
| 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 |
| cause.popQuizId | String | The Pop-up Quiz ID |
| cause.action | Integer | The action type:- `1`: The teacher starts taking the quiz
- `2`: The teacher finishes taking the quiz
- `3`: The student hands over the answer
- `4`: The information is updated |
| 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 |
| widgetUuid | String | The widget ID |
| changeProperties | Object | The changed properties |
| changeProperties.extra | Object | The extra information of the changed properties |
| changeProperties.extra.pollDetails | Map\ | 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 |
| cause.popQuizId | String | The Pop-up Quiz ID |
| cause.action | Integer | The action type:- `1`: The teacher starts taking the quiz
- `2`: The teacher finishes taking the quiz
- `3`: The student hands over the answer
- `4`: The information is updated |
| 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 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 |
| widgetUuid | String | The widget ID |
| 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\ | 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 |
| 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 |
#### Response example [#response-example-16]
* After the teacher clicks the Start button to start a poll, the summarized data of the Polling widget updates:
```json
"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:
```json
"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:
```json
"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:
```json
"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 [#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. |
## Events [#events]
This section lists all types of events that you can get through the [Get classroom events](#get-classroom-events) method.
### The classroom state changes [#the-classroom-state-changes]
When the `cmd` property of an event is `1`, the event indicates the classroom state changes, and the `data` property contains the following fields:
| Parameter | Type | Description |
| ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `startTime` | Number | The Unix timestamp (in milliseconds) when the class starts, in UTC. This property is available after the state of the classroom changes to `1"`. |
| `state` | Integer | The current state of the classroom:- `0`: Not started.
- `1`: In progress.
- `2`: Ended.
- `3`: After the run-late time of a class, the room is closed and users can no longer enter the room. |
| `endTime` | Number | The Unix timestamp (in milliseconds) when the class ends, in UTC. This property is available after the state of the classroom changes to `2`. |
| `closeTime` | Number | The Unix timestamp (in milliseconds) when the classroom closes, in UTC. This property is available after the state of the classroom changes to `3`. |
**Example**
```json
{
"startTime": 1611561776588,
"state": 1
}
```
### Receives a room chat message [#receives-a-room-chat-message]
When the `cmd` property of an event is `3`, the event indicates the server receives a room chat message, and the` data` contains the following fields:
| Parameter | Type | Description |
| ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fromUser` | Object | The user who sends this message. This object contains the following fields:- `userUuid`: String. The user ID.
- `userName`: String. The user name.
- `role`: Integer. The user role. This parameter can be set as one of the following values:
* `1`: Teacher.
* `2`: Student. |
| `message` | String | The message. |
| `type` | Integer | The type of the message. Temporarily, you can only set this parameter as `1`(text messages). |
**Example**
```json
{
"fromUser": {
"role": "host",
"userName": "jason",
"userUuid": "jason1"
},
"message": "aa",
"type": 1
}
```
### Users enter or leave the classroom [#users-enter-or-leave-the-classroom]
When the `cmd` property of an event is `20`, the event indicates that users have entered or left the classroom. `data` includes the following fields:
| Parameter | Type | Description |
| -------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `total` | Integer | The total number of users in the classroom after this event. |
| `onlineUsers` | Object Array | The new users who entered the classroom at the time of this event. This object contains the following fields:- `userName`: String. The user name.
- `userUuid`: String. The user ID.
- `role`: Integer. The user role. This parameter can be set as one of the following values:
* `1`: Teacher.
* `2`: Student.
- `userProperties`: Object. The user property.
- `streamUuid`: String. The ID of the stream, which is also the uid used when joining an RTC SDK channel.
- `type`: Integer. The reasons why the user enters the room:
* `1`: The user enters the classroom in a normal way.
* `2`: The user re-enters the classroom.
- `updateTime`: Number. The time when the user enters the classroom, Unix timestamp (milliseconds), UTC time. |
| `offlineUsers` | Object Array | The new users who have left the classroom at the time of this event. This object contains the following fields:- `userName`: String. The user name.
- `userUuid`: String. The user ID.
- `role`: Integer. The user role. This parameter can be set as one of the following values:
* `1`: Teacher.
* `2`: Student.
- `userProperties`: Object. The user property.
- `streamUuid`: String. The ID of the stream, which is also the uid used when joining an RTC SDK channel.
- `type`: Integer. The reasons why the user leaves the classroom:
* `1`: The user leaves the classroom on the client, such as leaving the class normally, the application is forcibly closed, or the user is disconnected due to poor network conditions.
* `2`: The user is kicked out of the classroom.
- `updateTime`: Number. The time when the user enters or leaves the classroom, Unix timestamp (in milliseconds), UTC time. |
**Example**
```json
{
"total": 3,
"onlineUsers": [
{
"userName": "",
"userUuid": "",
"role": "0",
"userProperties": {},
"streamUuid": "",
"type": 1,
"updateTime": 1611561776588
}
],
"offlineUsers": [
{
"userName": "",
"userUuid": "",
"role": "0",
"userProperties": {},
"streamUuid": "",
"type": 1,
"updateTime": 1611561776588
}
]
}
```
### The recording state changes [#the-recording-state-changes]
When the `cmd` property of an event is `1001`, the event indicates the recording state changes, and the `data` property contains the following fields:
| Parameter | Type | Description |
| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recordId` | String | This is 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. This field is available only when `state` is `1`. |
| `sid` | String | The `sid` of the Agora Cloud Recording service. This field is available only when `state` is `1`. |
| `resourceId` | String | The `resourceId` of the Agora Cloud Recording service. This field is available only when `state` is `1`. |
| `state` | Integer | The current recording state:- `2`: Recording has ended.
- `1`: In recording. |
| `startTime` | Number | The Unix timestamp (in milliseconds) when the recording starts, in UTC. This property is available after the recording state changes to "Started". |
| `streamingUrl` | Object | The URL address for the webpage after being pushed to the CDN. Students can use this URL to watch the teaching online. |
**Example**
```json
{
"recordId": "xxx",
"sid": "xxx",
"resourceId": "xxx",
"state": 1,
"startTime": 1611564500488
}
```
### The number of rewards changes [#the-number-of-rewards-changes]
When the `cmd` property of an event is `1101`, the event indicates the number of rewards changes, and the `data` property contains the following fields:
| Parameter | Type | Description |
| :-------------- | :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rewardDetails` | Object Array | Each object represents the rewards of a user and contains the following fields:- `userUuid`: String. The user ID.
- `changedReward`: Integer. The number of changed rewards.
- `total`: Integer. The total number of rewards after the change. |
| `updateTime` | Number | The Unix timestamp (in milliseconds) when the rewards change, in UTC. |
**Example**
```json
{
"rewardDetails": [
{
"userUuid": "",
"changedReward": 1,
"totalReward": 10
}
],
"updateTime": 1611564500488
}
```
### The resources in the classroom change [#the-resources-in-the-classroom-change]
When the `cmd` property of an event is `1003`, the event indicates the resources in the classroom change, and the `data` property contains the following fields:
| Parameter | Type | Description |
| :---------- | :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Parameter | Type | Description |
| `resources` | Object Array | Each object represents a public resource and contains the following fields:- `resourceUuid`: String. The resource ID.
- `resourceName`: String. The resource name.
- `size`: Number. The resourc size (bytes).
- `url`: String. The URL address of the resource.
- `taskUuid`: String. The ID of the file conversion task.
- `taskToken`: String. The token used for the file conversion task.
- `taskProgress`: Object. The progress of a file conversion task. |
| `operator` | Object | It contains the following fields:- `userUuid`: String. The user ID.
- `userName`: String. The user name.
- `role`: Integer. Th user role. |
| `action` | Integer | The resource change type:- `1`: The resource is added or updated.
- `2`: The resource is deleted. |
**Example**
```json
{
"resources": [
{
"resourceUuid": "",
"resourceName": "1",
"size": 1024,
"url": "http://xxx.com/ooo",
"taskUuid": "",
"taskToken": "",
"taskProgress": {}
}
],
"operator": {
"role": "1",
"userName": "jason",
"userUuid": "jason1"
},
"action": 1
}
```
### The users "on the stage" change [#the-users-on-the-stage-change]
When the `cmd` property of an event is `1501`, the event indicates the users "on the stage" change, and the` data` property contains the following fields:
| Parameter | Type | Description |
| :-------------------- | :----------- | :--------------------------------------------------------------------------------------------------------------------------------- |
| `acceptedUsers` | Object Array | The list of users who are now "on the stage". The object contains the following fields:- `userUuid`: String. The user ID. |
| `addAcceptedUsers` | Object Array | The list of users who have just "gone onto the stage". The object contains the following fields:- `userUuid`: String. The user ID. |
| `removeAcceptedUsers` | Object Array | The list of users who have just "left the stage". The object contains the following fields:- `userUuid`: String. The user ID. |
**Example**
```json
{
"acceptedUsers": [
{
"userUuid": ""
}
],
"addAcceptedUsers": [
{
"userUuid": ""
}
],
"removeAcceptedUsers": [
{
"userUuid": ""
}
]
}
```
### The users who wave their hands change [#the-users-who-wave-their-hands-change]
When the `cmd` property of an event is `1502`, the event indicates the users who wave their hands change, and the `data` property contains the following fields:
| Parameter | Type | Description |
| :-------------------- | :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `progressUsers` | Object Array | The list of users who are waving their hands. The object contains the following fields:- `userUuid`: String. The user ID.
- `payload`: Object. |
| `addProgressUsers` | Object Array | The list of users who have just started waving their hands. The object contains the following fields:- `userUuid`: String. The user ID.
- `payload`: Object. |
| `removeProgressUsers` | Object Array | The list of users who have just stopped waving their hands. The object contains the following fields:- `userUuid`: String. The user ID.
- `payload`: Object. |
**Example**
```json
{
"progressUsers": [
{
"userUuid": "",
"payload": {}
}
],
"addProgressUsers": [
{
"userUuid": "",
"payload": {}
}
],
"removeProgressUsers": [
{
"userUuid": "",
"payload": {}
}
]
}
```
## Ensure service reliability [#ensure-service-reliability]
This section presents the overall strategy you use to ensure high availability of REST services.
### Switch the domain name [#switch-the-domain-name]
To ensure high availability of REST services, Agora enables you to switch domain names when you experience service outage due to regional network failures. Take the following steps to set up and switch your domain name:
1. Set the primary domain name based on the location of your service server:
* If the DNS address of the service server is located in a country or region other than mainland China, set the primary domain name to `api.agora.io`.
* If the DNS address of the service server is in mainland China, set the primary domain name to `api.sd-rtn.com`.
2. If your attempt to initiate a RESTful API request using the primary domain fails, set up your retry strategy as follows:
1. **Primary domain retry**: Retry using the same primary domain name.
2. **Alternate domain retry**:
* If the current primary domain name is `api.sd-rtn.com`, use `api.agora.io` as the alternate domain name.
* If the current primary domain name is `api.agora.io`, use `api.sd-rtn.com` as the alternate domain name.
3. **Adjacent domain retry**: If alternate domain retry fails, retry using the domain name adjacent to the current region.
For example, suppose your business server is located in Europe. You set the primary domain name to `api.agora.io`, and the business server resolves the primary domain name to Germany. Germany is located in central Europe (`api-eu-central-1.agora.io`). The [domain name table](#domain-name-table) shows that the adjacent area is West Europe. Use the `api-eu-west-1.agora.io` or `api-eu-west-1.sd-rtn.com` domain name to retry.
#### Precautions [#precautions]
Take the following precautions when setting up your retry strategy:
* To avoid exceeding the QPS limit with retry requests, best practice is to use a back-off strategy. For example, wait 1 second before you retry for the first time, wait 3 seconds before retrying the second time, and wait 6 seconds before retry a third time.
* If the request fails because of a network problem rather than a DNS domain name resolution problem, skip alternate domain retry and proceed to adjacent domain retry.
* Before switching to the region domain name, ensure that the REST services you wish to use, for example, cloud recording or channel management, are deployed in that region.
### Domain name table [#domain-name-table]
The following table shows the primary and region domain names for various regions.
| Primary domain name | Region domain name | Region |
| :------------------ | :------------------------------ | :--------------------- |
| `api.sd-rtn.com` | `api-us-west-1.sd-rtn.com` | Western United States |
| | `api-us-east-1.sd-rtn.com` | Eastern United States |
| | `api-ap-southeast-1.sd-rtn.com` | Southeast Asia Pacific |
| | `api-ap-northeast-1.sd-rtn.com` | Northeast Asia Pacific |
| | `api-eu-west-1.sd-rtn.com` | Western Europe |
| | `api-eu-central-1.sd-rtn.com` | Central Europe |
| | `api-cn-east-1.sd-rtn.com` | East China |
| | `api-cn-north-1.sd-rtn.com` | North China |
| `api.agora.io` | `api-us-west-1.agora.io` | Western United States |
| | `api-us-east-1.agora.io` | Eastern United States |
| | `api-ap-southeast-1.agora.io` | Southeast Asia Pacific |
| | `api-ap-northeast-1.agora.io` | Northeast Asia Pacific |
| | `api-eu-west-1.agora.io` | Western Europe |
| | `api-eu-central-1.agora.io` | Central Europe |
| | `api-cn-east-1.agora.io` | East China |
| | `api-cn-north-1.agora.io` | North China |