Skip to main content

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.

Data format

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

Authentication

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

  • The Signaling token generated at your server.
  • The uid you use to generate the Signaling token.

For details, see Generate an RTM Token.

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.

ParameterTypeDescription
regionString(Required) The region for connection. Flexible Classroom supports the following regions:
  • cn: Mainland China.
  • ap: Asia Pacific.
  • eu: Europe.
  • na: North America.
  • appIdString(Required) Agora App ID.
    roomUuidString(Required) The classroom ID. This is the globally unique identifier of a classroom. It is also used as the channel name when a user joins an RTC or RTM channel. The string length must be less than 64 bytes. 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:

    ParameterTypeDescription
    roomTypeString(Required) The type of the classroom. You can set the value to :
    • 0: One-to-one classroom.
    • 2: Lecture hall.
    • 4: Small classroom.
    Once set, this parameter value cannot be changed.
    roomNameString(Required) The name of the classroom.
    roomPropertiesObject(Optional) The properties of the classroom.
    roomProperties.scheduleObject(Optional) The schedule of the classroom.
    roomProperties.schedule.startTimeInteger(Optional) The start time of the class. Once set, this parameter value cannot be changed.
    roomProperties.schedule.durationInteger(Optional) The duration of the class.
    roomProperties.schedule.closeDelayInteger(Optional) The delay of the class end time.
    roomProperties.processesObject(Optional) The process of inviting students to go "on the stage".
    roomProperties.processes.handsUpObject(Optional) The settings of "on the stage".
    roomProperties.processes.handsUp.maxAcceptInteger(Optional) The maximum number of students "on the stage".
    roomProperties.hostingSceneObject(Optional) The unique classroom properties of a vocational lecture hall.
    roomProperties.hostingScene.videoURLString(Optional) The teacher's CDN stream URL (main video URL).
    roomProperties.hostingScene.reserveVideoURLString(Optional) The teacher's CDN stream URL (backup video URL).
    roomProperties.hostingScene.finishTypeInteger(Optional) The way the class ends.
  • 0: The class automatically ends when the recording finishes playing.
  • 1: The class ends when the teacher clicks the End Class button; this also stops the recording playback.
  • Request example


    _16
    {
    _16
    "roomName": "jasoncai61734",
    _16
    "roomType": 4,
    _16
    "roomProperties": {
    _16
    "schedule": {
    _16
    "startTime": 1655452800000,
    _16
    "duration": 600,
    _16
    "closeDelay": 300
    _16
    },
    _16
    "processes": {
    _16
    "handsUp": {
    _16
    "maxAccept": 10
    _16
    }
    _16
    }
    _16
    }
    _16
    }

    Response parameters

    ParameterTypeDescription
    codeIntegerRequest status code:
    • 0: The request succeeds.
    • Non-zero: The request fails.
    msgStringDetailed information about the code.
    tsNumberThe current Unix timestamp (in milliseconds) of the server in UTC.

    Response example


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

    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.

    ParameterTypeDescription
    regionString(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.
  • appIdString(Required) Agora App ID.
    roomUuidString(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 achannel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All numeric characters.
  • 0-9
  • The space character.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
  • userUuidString(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 bytes. Supported character scopes are:
  • 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.

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

    Request example

    Request URL


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

    Request Body


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

    Response parameters

    ParameterTypeDescription
    codeIntegerBusiness status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
  • msgStringThe detailed information.
    tsNumberThe current Unix timestamp (in milliseconds) of the server in UTC.

    Response example


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

    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.

    ParameterTypeDescription
    regionString(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.
  • appIdString(Required) Agora App ID.
    roomUuidString(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 achannel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0-9
  • The space character
  • "!", 1"#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
  • stateInteger(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


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

    Response parameters

    ParameterTypeDescription
    codeIntegerBusiness status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
  • msgStringThe detailed information.
    tsNumberThe current Unix timestamp (in milliseconds) of the server in UTC.

    Response example


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

    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.

    ParameterTypeDescription
    regionString(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.
  • appIdString(Required) Agora App ID.
    roomUuidString(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 achannel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All numeric characters.
  • 0-9
  • The space character.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
  • stateInteger(Required) The recording state:
  • 0: Stop recoding.
  • 1: Started.
  • Request body parameters

    Pass in the following parameters in the request body.

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

    Request example

    Request URL


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

    Request Body


    _8
    {
    _8
    "mode": "web",
    _8
    "webRecordConfig": {
    _8
    "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}",
    _8
    "rootUrl":"https://xxx.yyy.zzz"
    _8
    },
    _8
    "retryTimeout": 60
    _8
    }

    Response parameters

    ParameterTypeDescription
    codeIntegerBusiness status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
  • msgStringThe detailed information.
    tsNumberThe current Unix timestamp (in milliseconds) of the server in UTC.

    Response example


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

    Update the recording configurations

    Description

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

    Prototype

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

    Request parameters

    URL parameters

    Pass the following parameter in the URL.

    ParameterTypeDescription
    regionString(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.
  • appIdString(Required) Agora App ID.
    roomUuidString(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 achannel. The string length must be less than 64 bytes. Supported character scopes are:
  • 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.

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

    Request example

    Request URL


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

    Request Body


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

    Response parameters

    ParameterTypeDescription
    codeIntegerBusiness status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
  • msgStringThe detailed information.
    tsNumberThe current Unix timestamp (in milliseconds) of the server in UTC.

    Response example


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

    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.

    ParameterTypeDescription
    regionString(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.
  • appIdString(Required) Agora App ID.
    roomUuidString(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 achannel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All numeric characters.
  • 0-9
  • The space character.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
  • Query parameters

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

    Request example

    Example one:


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

    Example two:


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

    Response parameters

    ParameterTypeDescription
    codeIntegerBusiness status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
  • msgStringThe detailed information.
    tsNumberThe current Unix timestamp (in milliseconds) of the server in UTC.
    dataObjectInclude 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 achannel.
      • recordId: The unique identifier of a recording session. A recording session starts when you call a method to start recording and ends when you call this method to stop recording.
      • startTime: The UTC timestamp when a recording session starts, in milliseconds.
      • endTime: The UTC timestamp when a recording session ends, in milliseconds.
      • resourceId: The resourceId of the Agora Cloud Recording service.
      • sid: The sid of the Agora Cloud Recording service.
      • recordUid: The UID used by the Agora Cloud Recording service in the channel.
      • boardAppId: The App Identifier of the Agora Interactive Whiteboard service.
      • boardToken: The SDK Token of the Agora Interactive Whiteboard service.
      • boardId: The unique identifier of a whiteboard session.
      • type: Integer, the recording type:
        • 1: Individual Recording
        • 2: Composite Recording
      • status: Integer, the recording state:
        • 1: In recording.
        • 2: Recording has ended.
      • url: String, the URL address of the recorded files in composite recording mode.
      • recordDetails: JSONArray. The JSON object contains the following fields:
        • url: String, the URL address of the recorded files in web page recording mode.
      • nextId: String, the starting ID of the next batch of data. If it is null, there is no next batch of data. If it is not null, use this nextId to continue the query until null is reported.
      • total: Integer, the total number of pieces of data.

    Response example


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

    Query a specified event

    Description

    Query a specified type of event in a specified classroom.

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

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

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

    Request parameters

    URL parameters

    Pass the following parameters in the URL.

    ParameterTypeDescription
    regionString(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.
  • appIdString(Required) Agora App ID.
    roomUuidString(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 achannel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All numeric characters.
  • 0-9
  • The space character.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
  • Query parameters

    ParameterTypeDescription
    nextIdString(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.
    cmdInteger(Optional) Event type. For details, see Flexible Classroom Cloud Service Events.

    Request example

    Request URL

    Example one:


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

    Example two:


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

    Response parameters

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

    Response example


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

    Get classroom events

    Description

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

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

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

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

    Request parameters

    URL parameters

    Pass the following parameter in the URL.

    ParameterTypeDescription
    regionString(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.
  • appIdString(Required) Agora App ID.

    Request example


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

    Response parameters

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


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

    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.

    ParameterTypeDescription
    regionString(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.
  • appIdString(Required) Agora App ID.
    roomUuidString(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 achannel. The string length must be less than 64 bytes. Supported character scopes are:
  • 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.

    ParameterTypeDescription
    propertiesObjectClassroom properties.
    causeObjectThe update reason.

    Request example

    Request Body


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

    Response parameters

    ParameterTypeDescription
    codeIntegerBusiness status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
  • msgStringThe detailed information.
    tsNumberThe current Unix timestamp (in milliseconds) of the server in UTC.

    Response example


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

    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.

    ParameterTypeDescription
    regionString(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.
  • appIdString(Required) Agora App ID.
    roomUuidString(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 achannel. The string length must be less than 64 bytes. Supported character scopes are:
  • 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.

    ParameterTypeDescription
    propertiesString arrayClassroom properties.
    causeObjectReason for deletion.

    Request example

    Request Body


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

    Response parameters

    ParameterTypeDescription
    codeIntegerBusiness status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
  • msgStringThe detailed information.
    tsNumberThe current Unix timestamp (in milliseconds) of the server in UTC.

    Response example


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

    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.

    ParameterTypeDescription
    regionString(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.
  • appIdString(Required) Agora App ID.
    roomUuidString(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 achannel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All numeric characters.
  • 0-9
  • The space character.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
  • userUuidString(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 bytes. Supported character scopes are:
  • 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.

    ParameterTypeDescription
    propertiesObjectThe user properties.
    causeObjectThe update reason.

    Request example

    Request Body


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

    Response parameters

    ParameterTypeDescription
    codeIntegerBusiness status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
  • msgStringThe detailed information.
    tsNumberThe current Unix timestamp (in milliseconds) of the server in UTC.

    Response example


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

    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.

    ParameterTypeDescription
    regionString(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.
  • appIdString(Required) Agora App ID.
    roomUuidString(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 achannel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All numeric characters.
  • 0-9
  • The space character.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
  • userUuidString(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 bytes. Supported character scopes are:
  • 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.

    ParameterTypeDescription
    propertiesString arrayThe user properties.
    causeObjectReason for deletion.

    Request example

    Request Body


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

    Response parameters

    ParameterTypeDescription
    codeIntegerBusiness status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
  • msgStringThe detailed information.
    tsNumberThe current Unix timestamp (in milliseconds) of the server in UTC.

    Response example


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

    Set the extApp properties

    Description

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

    Prototype

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

    Request parameters

    URL parameters

    Pass the following parameters in the URL.

    ParameterTypeDescription
    regionString(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.
  • appIdString(Required) Agora App ID.
    roomUuidString(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 achannel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All numeric characters.
  • 0-9
  • The space character.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
  • extAppUuidString(Required) The extApp ID. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All numeric characters.
  • 0-9
  • The space character.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
  • Request body parameters

    Pass in the following parameters in the request body.

    ParameterTypeDescription
    propertiesObjectThe user properties.
    commonObjectThe JSON object contains the following fields:
  • state: Integer, the state of extApp. 0 means disabled, and 1 means enabled.
  • causeObjectThe update reason.

    Request example

    Request Body


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

    Response parameters

    ParameterTypeDescription
    codeIntegerBusiness status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
  • msgStringThe detailed information.
    tsNumberThe current Unix timestamp (in milliseconds) of the server in UTC.

    Response example


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

    Delete the extApp properties

    Description

    Delete the properties of the extApp in a specified classroom.

    Prototype

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

    Request parameters

    URL parameters

    Pass the following parameters in the URL.

    ParameterTypeDescription
    regionString(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.
  • appIdString(Required) Agora App ID.
    roomUuidString(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 achannel. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All numeric characters.
  • 0-9
  • The space character.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
  • extAppUuidString(Required) The extApp ID. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All numeric characters.
  • 0-9
  • The space character.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
  • Request body parameters

    Pass in the following parameters in the request body.

    ParameterTypeDescription
    propertiesString arrayThe user properties.
    causeObjectReason for deletion.

    Request example

    Request Body


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

    Response parameters

    ParameterTypeDescription
    codeIntegerBusiness status code:
  • 0: The request succeeds.
  • Non-zero: The request fails.
  • msgStringThe detailed information.
    tsNumberThe current Unix timestamp (in milliseconds) of the server in UTC.

    Response example


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

    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:

    ParameterTypeDescription
    appIdString(Required) Agora App ID.
    roomUuidString(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 achannel. The string length must be less than 64 bytes.

    Query parameters

    ParameterTypeDescription
    nextIdString(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.
    countInteger(Optional) The number of pieces of data in this batch. The default value is 100.

    Response parameters

    The fields returned in data vary in different situations.

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

      Field nameTypeDescription
      actionIntegerThe action type
      changePropertiesObjectThe changed properties
      changeProperties.extraObjectThe extra information of the changed properties
      changeProperties.extra.correctItemsObject[]The correct choice
      changeProperties.extra.correctCountIntegerThe number of students who have made the correct choice
      changeProperties.extra.answerStateIntegerThe status of this quiz:
      • 1 : In progress
      • 0: Ended
      changeProperties.extra.receiveQuestionTimeLongThe time when the students receive the question
      changeProperties.extra.popupQuizIdStringThe question ID
      changeProperties.extra.averageAccuracyFloatThe rate at which the correct choice is made for this question
      changeProperties.extra.totalCountIntegerThe total number of students who have submitted their answers to this question
      changeProperties.extra.itemsObject[]The options of this question
      changeProperties.stateIntegerThe state of the Pop-up Quiz widget:
      • 0: Inactive
      • 1: Active
      causeStringThe reason for the property change
      operatorObjectThe operator of the property change
      operator.userUuidStringThe ID of the operator
      operator.userNameStringThe name of the operator
      operator.roleStringThe role of the operator
    • After a student submits the answer, the student's data updates. data contains the following fields:

      Field nameTypeDescription
      actionIntegerThe action type
      changePropertiesObjectThe changed properties
      changeProperties.lastCommitTimeLongThe last submit time
      changeProperties.popupQuizIdStringThe question ID
      changeProperties.selectedItemsObject[]The answer submitted by this student
      changeProperties.isCorrectBooleanWhether the answer submitted by the student is correct
      causeStringThe reason for the property change
      operatorObjectThe operator of the property change
      operator.userUuidStringThe ID of the operator
      operator.userNameStringThe name of the operator
      operator.roleStringThe role of the operator
      fromUserObjectThe user who starts this quiz
      fromUser.userUuidStringThe ID of the user who starts this quiz
      fromUser.userNameStringThe name of the user who starts this quiz
      fromUser.roleStringThe 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 nameTypeDescription
      actionIntegerThe action type
      changePropertiesObjectThe changed properties
      changeProperties.extraObjectThe extra information of the changed properties
      changeProperties.extra.selectedCountIntegerThe number of students who have submitted their answers
      changeProperties.extra.correctCountIntegerThe number of students who have made the correct choice
      changeProperties.extra.averageAccuracyFloatThe rate at which the correct choice is made for this question
      changeProperties.extra.totalCountIntegerThe total number of students who have submitted their answers to this question
      causeStringThe reason for the property change
      operatorObjectThe operator of the property change
      operator.userUuidStringThe ID of the operator
      operator.userNameStringThe name of the operator
      operator.roleStringThe 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 nameTypeDescription
      actionIntegerThe action type
      changePropertiesObjectThe changed properties
      changeProperties.extraObjectThe extra information of the changed properties
      changeProperties.extra.selectedCountIntegerThe number of students who have submitted their answers
      changeProperties.extra.correctCountIntegerThe number of students who have made the correct choice
      changeProperties.extra.answerStateIntegerThe status of this quiz:
      • 1 : In progress
      • 0: Ended
      changeProperties.extra.averageAccuracyFloatThe rate at which the correct choice is made for this question
      changeProperties.extra.totalCountIntegerThe total number of students who have submitted their answers to this question
      causeStringThe reason for the property change
      operatorObjectThe operator of the property change
      operator.userUuidStringThe ID of the operator
      operator.userNameStringThe name of the operator
      operator.roleStringThe 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:


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

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


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

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


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

    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:

    ParameterTypeDescription
    appIdString(Required) Agora App ID.
    roomUuidString(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 achannel. The string length must be less than 64 bytes.

    Query parameters

    ParameterTypeDescription
    nextIdString(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.
    countInteger(Optional) The number of pieces of data in this batch. The default value is 100.

    Response parameters

    The fields returned in data vary in different situations.

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

      Field nameTypeDescription
      actionIntegerThe action type
      changePropertiesObjectThe changed properties
      changeProperties.extraObjectThe extra information of the changed properties
      changeProperties.extra.modeIntegerThe polling mode:
      • 1: Single-choice
      • 2: Multiple-choice
      changeProperties.extra.pollingStateIntegerThe status of this poll:
      • 1 : In progress
      • 0: Ended
      changeProperties.extra.pollDetailsMap<String, Object>The polling results. key is the option index, starting from 0.
      changeProperties.extra.pollDetails.numIntegerThe number of students who have selected this option
      changeProperties.extra.pollDetails.percentageFloatThe percentage of students who have selected this option in students who have submitted their choices
      changeProperties.extra.pollIdStringThe poll ID
      changeProperties.extra.pollItemsObjectThe option content
      changeProperties.stateIntegerThe state of the Polling widget:
      • 0: Inactive
      • 1: Active
      causeStringThe reason for the property change
      operatorObjectThe operator of the property change
      operator.userUuidStringThe ID of the operator
      operator.userNameStringThe name of the operator
      operator.roleStringThe role of the operator
    • After a student submits the choice, the student's data updates. data contains the following fields:

      Field nameTypeDescription
      actionIntegerThe action type
      changePropertiesObjectThe changed properties
      changeProperties.extraObjectThe extra information of the changed properties
      changeProperties.extra.pollIdStringThe poll ID
      changeProperties.extra.selectIndexObject[]The index of the option selected by this student
      causeStringThe reason for the property change
      operatorObjectThe operator of the property change
      operator.userUuidStringThe ID of the operator
      operator.userNameStringThe name of the operator
      operator.roleStringThe role of the operator
      fromUserObjectThe user who starts this poll
      fromUser.userUuidStringThe ID of the user who starts this poll
      fromUser.userNameStringThe name of the user who starts this poll
      fromUser.roleStringThe 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 nameTypeDescription
      actionIntegerThe action type
      changePropertiesObjectThe changed properties
      changeProperties.extraObjectThe extra information of the changed properties
      changeProperties.extra.pollDetailsMap<String, Object>The polling results. key is the option index, starting from 0.
      changeProperties.extra.pollDetails.numIntegerThe number of students who have selected this option
      changeProperties.extra.pollDetails.percentageFloatThe percentage of students who have selected this option in students who have submitted their choices
      changeProperties.extra.pollIdStringThe poll ID
      causeStringThe reason for the property change
      operatorObjectThe operator of the property change
      operator.userUuidStringThe ID of the operator
      operator.userNameStringThe name of the operator
      operator.roleStringThe role of the operator
    • After the teacher ends the poll, the summarized data of the Polling widget updates. data contains the following fields:

      Field nameTypeDescription
      actionIntegerThe action type
      changePropertiesObjectThe changed properties
      changeProperties.extraObjectThe extra information of the changed properties
      changeProperties.extra.pollingStateIntegerThe status of this poll:
      • 1 : In progress
      • 0: Ended
      changeProperties.extra.pollDetailsMap<String, Object>The polling results. key is the option index, starting from 0.
      changeProperties.extra.pollDetails.numIntegerThe number of students who have selected this option
      changeProperties.extra.pollDetails.percentageFloatThe percentage of students who have selected this option in students who have submitted their choices
      changeProperties.extra.pollIdStringThe poll ID
      causeStringThe reason for the property change
      operatorObjectThe operator of the property change
      operator.userUuidStringThe ID of the operator
      operator.userNameStringThe name of the operator
      operator.roleStringThe role of the operator

    Response example

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


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

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


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

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


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

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


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

    Status code

    Response status codeBusiness status codeDescription
    2000The request succeeds.
    400400The request parameter is incorrect.
    401N/APossible reasons:
  • The App ID is invalid.
  • Unauthorized. Incorrect x-agora-uid or x-agora-token.
  • 40330403200The classroom is muted globally. Users cannot send chat messages.
    404N/AThe server cannot find the requested resource.
    40420404100The classroom does not exist.
    40420404200The user does not exist.
    40930409410The recording has not been started.
    40930409411The recording has not been ended.
    40930409100The class has been started.
    40930409101The class has been ended.
    500500The server has an internal error and cannot process the request.
    503N/AInternal 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:

    ParameterTypeDescription
    startTimeNumberThe Unix timestamp (in milliseconds) when the classroom starts, in UTC. This property is available after the state of the classroom changes to "Started".
    stateIntegerThe 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.

    Example


    _4
    {
    _4
    "startTime":1611561776588,
    _4
    "state":1
    _4
    }

    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:

    ParameterTypeDescription
    fromUserObjectThe 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.
    messageStringThe message.
    typeIntegerThe type of the message. Temporarily, you can only set this parameter as 1(text messages).

    Example


    _9
    {
    _9
    "fromUser":{
    _9
    "role":"host",
    _9
    "userName":"jason",
    _9
    "userUuid":"jason1"
    _9
    },
    _9
    "message":"aa",
    _9
    "type":1
    _9
    }

    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:

    ParameterTypeDescription
    totalIntegerThe total number of users who have entered and left the classroom.
    onlineUsersObject ArrayThe users who have entered the classroom. 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 Video 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.
    offlineUsersObject ArrayThe users who have left the classroom. 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 Video 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


    _25
    {
    _25
    "total":3,
    _25
    "onlineUsers":[
    _25
    {
    _25
    "userName":"",
    _25
    "userUuid":"",
    _25
    "role":"0",
    _25
    "userProperties":{ },
    _25
    "streamUuid":"",
    _25
    "type":1,
    _25
    "updateTime":1611561776588
    _25
    }
    _25
    ],
    _25
    "offlineUsers":[
    _25
    {
    _25
    "userName":"",
    _25
    "userUuid":"",
    _25
    "role":"0",
    _25
    "userProperties":{},
    _25
    "streamUuid":"",
    _25
    "type":1,
    _25
    "updateTime":1611561776588
    _25
    }
    _25
    ]
    _25
    }

    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:

    ParameterTypeDescription
    recordIdStringThis 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.
    sidStringThe sid of the Agora Cloud Recording service. This field is available only when state is 1.
    resourceIdStringThe resourceId of the Agora Cloud Recording service. This field is available only when state is 1.
    stateIntegerThe current recording state:
    • 2: Recording has ended.
    • 1: In recording.
    startTimeNumberThe Unix timestamp (in milliseconds) when the recording starts, in UTC. This property is available after the recording state changes to "Started".

    Example


    _7
    {
    _7
    "recordId":"xxx",
    _7
    "sid":"xxx",
    _7
    "resourceId":"xxx",
    _7
    "state":1,
    _7
    "startTime":1611564500488
    _7
    }

    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:

    ParameterTypeDescription
    rewardDetailsObject ArrayEach 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.
  • updateTimeNumberThe Unix timestamp (in milliseconds) when the rewards change, in UTC.

    Example


    _8
    {
    _8
    "rewardDetails":[ {
    _8
    "userUuid":"",
    _8
    "changedReward": 1,
    _8
    "totalReward": 10
    _8
    } ],
    _8
    "updateTime":1611564500488
    _8
    }

    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:

    ParameterTypeDescription
    ParameterTypeDescription
    resourcesObject ArrayEach 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.
  • operatorObjectIt contains the following fields:
  • userUuid: String. The user ID.
  • userName: String. The user name.
  • role: Integer. Th user role.
  • actionIntegerThe resource change type:
  • 1: The resource is added or updated.
  • 2: The resource is deleted.
  • Example


    _17
    {
    _17
    "resources": [{
    _17
    "resourceUuid":"",
    _17
    "resourceName": "1",
    _17
    "size": 1024,
    _17
    "url": "http://xxx.com/ooo",
    _17
    "taskUuid": "",
    _17
    "taskToken": "",
    _17
    "taskProgress": {},
    _17
    } ],
    _17
    "operator":{
    _17
    "role":"1",
    _17
    "userName":"jason",
    _17
    "userUuid":"jason1"
    _17
    },
    _17
    "action": 1
    _17
    }

    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:

    ParameterTypeDescription
    acceptedUsersObject ArrayThe list of users who are now "on the stage". The object contains the following fields:
  • userUuid: String. The user ID.
  • addAcceptedUsersObject ArrayThe list of users who have just "gone onto the stage". The object contains the following fields:
  • userUuid: String. The user ID.
  • removeAcceptedUsersObject ArrayThe list of users who have just "left the stage". The object contains the following fields:
  • userUuid: String. The user ID.
  • Example


    _11
    {
    _11
    "acceptedUsers": [{
    _11
    "userUuid":""
    _11
    }],
    _11
    "addAcceptedUsers": [{
    _11
    "userUuid":""
    _11
    }],
    _11
    "removeAcceptedUsers": [{
    _11
    "userUuid":""
    _11
    }]
    _11
    }

    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:

    ParameterTypeDescription
    progressUsersObject ArrayThe list of users who are waving their hands. The object contains the following fields:
  • userUuid: String. The user ID.
  • payload: Object.
  • addProgressUsersObject ArrayThe list of users who have just started waving their hands. The object contains the following fields:
  • userUuid: String. The user ID.
  • payload: Object.
  • removeProgressUsersObject ArrayThe list of users who have just stopped waving their hands. The object contains the following fields:
  • userUuid: String. The user ID.
  • payload: Object.
  • Example


    _14
    {
    _14
    "progressUsers": [{
    _14
    "userUuid":"",
    _14
    "payload":{}
    _14
    }],
    _14
    "addProgressUsers": [{
    _14
    "userUuid":"",
    _14
    "payload": {}
    _14
    }],
    _14
    "removeProgressUsers": [{
    _14
    "userUuid":"",
    _14
    "payload": {}
    _14
    }]
    _14
    }