Classroom REST API
This page provides detailed help for the Flexible Classroom RESTful APIs.
Basic information
Server
All requests are sent to the host api.agora.io
. See Ensure service reliability for alternate domain names.
Data format
The Content-Type of all requests is application/json
.
Authentication
Flexible Classroom Cloud Service uses tokens for authentication. You need to put the corresponding information into the Authorization: agora token=
field when sending your HTTP request. For details, see Secure authentication with tokens.
Classroom-related
Create a classroom
Description
Call this method to create a classroom. After it is created, the classroom is reserved for five days.
Prototype
- Method: POST
- Endpoint:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}
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:
|
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:
|
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 :
|
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 (s).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. |
roomProperties.schedule.closeDelay | Integer | (Optional) The delay of the class end time (s). 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 is as "" or do not set this parameter. In the cloud classroom scenario, 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:
Request example
Response parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Request status code:
|
msg | String | Detailed information about the code. |
ts | Number | The current Unix timestamp (in milliseconds) of the server in UTC. |
Response example
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
Description
Returns all information about the room object.
Prototype
- Method: GET
- Endpoint:
{region}/edu/apps/{appId}/v2/rooms/{roomUuid}
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:
|
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:
|
Request example
Response parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Request status code:
|
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:
|
Response example
Set the classroom state
Description
Call this method to set the classroom state: Not started, Started, Ended.
Prototype
- Method: PUT
- Endpoint:
/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/states/{state}
Request parameters
URL parameters
Pass the following parameter in the URL.
Parameter | Type | Description |
---|---|---|
region | String | (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
|
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:
|
state | Integer | (Required) The classroom state:
|
Request example
Response parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Business status code:
|
msg | String | The detailed information. |
ts | Number | The current Unix timestamp (in milliseconds) of the server in UTC. |
Response example
Update custom classroom properties
Description
Add or update the custom properties of a specified classroom.
Prototype
- Method: PUT
- Endpoint:
/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/properties
Request parameters
URL parameters
Pass the following parameters in the URL:
Parameter | Type | Description |
---|---|---|
region | String | (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
|
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:
|
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 scenarios. |
cause | Object | The update reason. |
Request example
Response parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Business status code:
|
msg | String | The detailed information. |
ts | Number | The current Unix timestamp (in milliseconds) of the server in UTC. |
Response example
Delete custom classroom properties
Description
Delete the custom properties of a specified classroom.
Prototype
- Method: DELETE
- Endpoint:
/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/properties
Request parameters
URL parameters
Pass the following parameters in the URL:
Parameter | Type | Description |
---|---|---|
region | String | (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
|
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:
|
Request body parameters
Pass in the following parameters in the request body.
Parameter | Type | Description |
---|---|---|
properties | String array | Classroom properties. |
cause | Object | Reason for deletion. |
Request example
Request Body
Response parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Business status code:
|
msg | String | The detailed information. |
ts | Number | The current Unix timestamp (in milliseconds) of the server in UTC. |
Response example
Create or remove breakout classrooms
Description
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
- Method: PUT
- Endpoint:
/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/groups/states/{state}
Request parameters
URL parameters
Pass the following parameters in the URL:
Parameter | Type | Description |
---|---|---|
region | String | (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
|
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:
|
state | Integer | Whether to enable breakout rooms:
|
Request body parameters
- To create breakout rooms, you need to set
state
to1
and pass in the following parameters in the request body. - To remove all breakout rooms, you need to set
state
to0
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:
|
Request example
Response parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Business status code:
|
msg | String | The detailed information. |
ts | Number | The current Unix timestamp (in milliseconds) of the server in UTC. |
Response example
Recording-related
Set the recording state
Description
Call this method to start or stop recording a specified classroom.
Prototype
- Method: PUT
- Endpoint:
/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/records/states/{state}
Request parameters
URL parameters
Pass the following parameter in the URL.
Parameter | Type | Description |
---|---|---|
region | String | (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
|
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:
|
state | Integer | (Required) The recording state:
|
Request body parameters
Pass in the following parameters in the request body.
Parameter | Type | Description |
---|---|---|
mode | String | (Optional) The recording mode:
|
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:
|
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
Response parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Business status code:
|
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:
|
Response example
Update the recording configurations
Description
Call this method during the recording to update the recording configurations. Every time this method is called, the previous configurations are overwritten.
Prototype
- Method: PATCH
- Endpoint:
/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/records/states/{state}
Request parameters
URL parameters
Pass the following parameter in the URL.
Parameter | Type | Description |
---|---|---|
region | String | (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
|
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:
|
Request body parameters
Pass in the following parameters in the request body.
Parameter | Type | Description |
---|---|---|
webRecordConfig | Object | (Optional) Recording configurations:
|
Request example
Response parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Business status code:
|
msg | String | The detailed information. |
ts | Number | The current Unix timestamp (in milliseconds) of the server in UTC. |
Response example
Get the recording list
Description
Get the recording list in a specified classroom.
You can fetch data in batches with the nextId
parameter. You can get up to 100 pieces of data for each batch.
Prototype
- Method: GET
- Endpoint:
/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/records
Request parameters
URL parameters
Pass the following parameter in the URL.
Parameter | Type | Description |
---|---|---|
region | String | (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
|
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:
|
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
Response parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Business status code:
|
msg | String | The detailed information. |
ts | Number | The current Unix timestamp (in milliseconds) of the server in UTC. |
data | Object | Include the following parameters:
|
Response example
User-related
Query a specific user
Prototype
- Method: GET
- Endpoint:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/users/{userUuid}
Request parameters
URL parameters
Pass the following parameter in the URL.
Parameter | Type | Description |
---|---|---|
region | String | (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:cn : Mainland China.ap : Asia Pacific.eu : Europe.na : North America. |
appId | String | (Required) Agora App ID. |
roomUUid | String | (Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 characters. The following characters are supported:
|
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: |
Request example
Response parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Business status code: |
msg | String | The detailed information. |
data | Object | Include the following parameters:
|
Response example
Update custom user properties
Description
Add or update the custom properties of a specified user.
Prototype
- Method: PUT
- Endpoint:
/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/users/{userUuid}/properties
Request parameters
URL parameters
Pass the following parameters in the URL:
Parameter | Type | Description |
---|---|---|
region | String | (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
|
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:
|
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:
|
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
Response parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Business status code:
|
msg | String | The detailed information. |
ts | Number | The current Unix timestamp (in milliseconds) of the server in UTC. |
Response example
Delete custom user properties
Description
Delete the custom properties of a specified user.
Prototype
- Method: DELETE
- Endpoint:
/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/users/{userUuid}/properties
Request parameters
URL parameters
Pass the following parameters in the URL:
Parameter | Type | Description |
---|---|---|
region | String | (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
|
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:
|
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:
|
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
Response parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Business status code:
|
msg | String | The detailed information. |
ts | Number | The current Unix timestamp (in milliseconds) of the server in UTC. |
Response example
Kick a user out of a classroom
Description
Call this method to kick a specified user out of a classroom. After a successful method call, the server triggers an event indicating a user leaves the classroom. You can use the dirty
parameter to determine whether the user can enter the classroom afterwards.
Prototype
- Method: POST
- Endpoint:
/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/users/{userUuid}/exit
Request parameters
URL parameters
Pass the following parameters in the URL:
Parameter | Type | Description |
---|---|---|
region | String | (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
|
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:
|
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:
|
Request body parameters
Pass in the following parameters in the request body.
Parameter | Type | Description |
---|---|---|
dirty | Object | (Optional) The user privilege:
|
Request example
Response parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Business status code:
|
msg | String | The detailed information. |
ts | Number | The current Unix timestamp (in milliseconds) of the server in UTC. |
Response example
Classroom event-related
Query a specified event
Description
Query a specified type of event in a specified classroom.
You can fetch data in batches with the nextId
parameter. You can get up to 100 pieces of data for each batch.
Prototype
- Method: GET
- Endpoint:
/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/sequences
Request parameters
URL parameters
Pass the following parameters in the URL:
Parameter | Type | Description |
---|---|---|
region | String | (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
|
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:
|
Query parameters
Parameter | Type | Description |
---|---|---|
nextId | String | (Optional) The starting ID of the next batch of data. When you call this method to get the data for the first time, leave this parameter empty or set it as null. Afterward, you can set this parameter as the nextId that you get in the response of the previous method call. |
cmd | Integer | (Optional) Event type. For details, see Flexible Classroom Cloud Service Events. |
Request example
Response parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Business status code:
|
msg | String | The detailed information. |
ts | Number | The current Unix timestamp (in milliseconds) of the server in UTC. |
data | Object | Include the following parameters:
|
Response example
Get all classroom events
Description
Get all events in the classrooms associated with a specified App ID.
You can call this method at regular intervals to listen for all the events that occur in the flexible classrooms.
Prototype
- Method: GET
- Endpoint:
/{region}/edu/polling/apps/{appId}/v2/rooms/sequences
Request parameters
URL parameters
Pass the following parameter in the URL.
Parameter | Type | Description |
---|---|---|
region | String | (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
|
appId | String | (Required) Agora App ID. |
Request example
Response parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Business status code:
|
msg | String | The detailed information. |
ts | Number | The current Unix timestamp (in milliseconds) of the server in UTC. |
data | Object | Include the following parameters:
|
Response example
Get data for pop-up quizzes
Prototype
- Method: GET
- Request path:
/edu/apps/{appId}/v2/rooms/{roomUUid}/widgets/popupQuiz/sequences
Request parameters
URL parameters
Pass the following parameters in the URL:
Parameter | Type | Description |
---|---|---|
region | String | (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
|
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
Response parameters
The fields returned in data
vary in different situations.
-
After the teacher clicks the Start button to start a quiz, the summarized data of the Pop-up Quiz widget updates.
data
contains the following fields:Field name Type Description action Integer The action type 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 progress0
: 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
: Inactive1
: 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 quiz2
: The teacher finishes taking the quiz3
: The student hands over the answer4
: 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 quiz2
: The teacher finishes taking the quiz3
: The student hands over the answer4
: 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 quiz2
: The teacher finishes taking the quiz3
: The student hands over the answer4
: 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 progress0
: 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 quiz2
: The teacher finishes taking the quiz3
: The student hands over the answer4
: 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
-
After the teacher clicks the Start button to start a quiz, the summarized data of the Pop-up Quiz widget updates:
-
After a student submits the answer, the student's data updates:
-
After the teacher ends the quiz, the summarized data of the Pop-up Quiz widget updates:
Get data for polls
Prototype
- Method: GET
- Request path:
/edu/apps/{appId}/v2/rooms/{roomUUid}/widgets/poll/sequences
Request parameters
URL parameters
Pass the following parameters in the URL:
Parameter | Type | Description |
---|---|---|
region | String | (Required) The region for connection. For details, see Network geofencing. Flexible Classroom supports the following regions:
|
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
Response parameters
The fields returned in data
vary in different situations.
-
After the teacher clicks the Start button to start a poll, the summarized data of the Polling widget updates.
data
contains the following fields:Field name Type Description action Integer The action type 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-choice2
: Multiple-choice
changeProperties.extra.pollingState Integer The status of this poll: 1
: In progress0
: Ended
changeProperties.extra.pollDetails Map<String, Object> The polling results. key
is the option index, starting from0
.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
: Inactive1
: 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 quiz2
: The teacher finishes taking the quiz3
: The student hands over the answer4
: 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 quiz2
: The teacher finishes taking the quiz3
: The student hands over the answer4
: 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<String, Object> The polling results. key
is the option index, starting from0
.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 quiz2
: The teacher finishes taking the quiz3
: The student hands over the answer4
: 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 progress0
: Ended
changeProperties.extra.pollDetails Map<String, Object> The polling results. key
is the option index, starting from0
.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
-
After the teacher clicks the Start button to start a poll, the summarized data of the Polling widget updates:
-
After a student submits the choice, the student's data updates:
-
After a student submits the choice, the summarized data of the Polling widget updates:
-
After the teacher ends the poll, the summarized data of the Polling widget updates:
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:
|
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
This section lists all types of events that you can get through the Get classroom events method.
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:
|
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
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:
|
message | String | The message. |
type | Integer | The type of the message. Temporarily, you can only set this parameter as 1 (text messages). |
Example
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:
|
offlineUsers | Object Array | The new users who have left the classroom at the time of this event. This object contains the following fields:
|
Example
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:
|
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
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:
|
updateTime | Number | The Unix timestamp (in milliseconds) when the rewards change, in UTC. |
Example
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:
|
operator | Object | It contains the following fields:
|
action | Integer | The resource change type:
|
Example
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:
|
addAcceptedUsers | Object Array | The list of users who have just "gone onto the stage". The object contains the following fields:
|
removeAcceptedUsers | Object Array | The list of users who have just "left the stage". The object contains the following fields:
|
Example
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:
|
addProgressUsers | Object Array | The list of users who have just started waving their hands. The object contains the following fields:
|
removeProgressUsers | Object Array | The list of users who have just stopped waving their hands. The object contains the following fields:
|
Example
Ensure service reliability
This section presents the overall strategy you use to ensure high availability of REST services.
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:
-
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
.
- 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
-
If your attempt to initiate a RESTful API request using the primary domain fails, set up your retry strategy as follows:
-
Primary domain retry: Retry using the same primary domain name.
-
Alternate domain retry:
- If the current primary domain name is
api.sd-rtn.com
, useapi.agora.io
as the alternate domain name. - If the current primary domain name is
api.agora.io
, useapi.sd-rtn.com
as the alternate domain name.
- If the current primary domain name is
-
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 shows that the adjacent area is West Europe. Use theapi-eu-west-1.agora.io
orapi-eu-west-1.sd-rtn.com
domain name to retry.
-
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
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 |