回调列表

业务回调接口通过 HTTP POST 接收以下 JSON 正文，并以 HTTP 2xx 确认接收。地址配置、请求头、验签和重试见回调接入。

支持以下 10 类回调。示例中的 ID、名称、地址、时间和错误文案仅用于说明格式。可选字段无值时省略，完整资源信息通过对应查询接口获取。

事件索引

事件	含义	示例中的状态
classroom.created	课堂创建完成	pending
classroom.updated	课堂资料更新	pending
classroom.started	课堂开课	live
classroom.ended	课堂结束	ended
classroom.expired	未开课课堂过期	expired
classroom.stage_changed	成员上下台	live
courseware.created	课件创建	queued
courseware.processing	课件开始转码	processing
courseware.ready	课件转码完成	ready
courseware.failed	课件转码失败	failed

公共结构与课堂字段

字段	类型	必填	含义
eventId	string	是	事件唯一标识；重试不变
type	string	是	完整事件名称
appId	string	是	所属应用
timestamp	string	是	事件产生时间，ISO 8601
data	object	是	随事件变化的数据

课堂事件的 data 均包含以下公共字段：

字段	类型	必填	含义
classroomId	string	是	课堂 ID
name	string	是	事件产生时的课堂名称
status	string	是	变更后状态：creating、pending、live、ended、expired
teacherEduUserId	string	否	已分配老师时的用户 ID

课堂创建完成

classroom.created

创建流程完成并保存课堂状态后发送。可用于关联业务课程与平台课堂；不表示客户端已进课。

data 附加字段	类型	必填	含义
fromStatus	string	是	创建流程的前态，当前为 creating。

立即开课会另发 classroom.started；此时本事件的 status 也可以为 live。

{
  "eventId": "evt_example_classroom_created",
  "type": "classroom.created",
  "appId": "app_example",
  "timestamp": "2026-10-09T02:00:00.000Z",
  "data": {
    "classroomId": "cls_example",
    "name": "数学课堂",
    "status": "pending",
    "teacherEduUserId": "eu_teacher",
    "fromStatus": "creating"
  }
}

课堂资料更新

classroom.updated

更新课堂名称或配置后发送。可用来触发业务侧刷新课堂详情。

data 附加字段	类型	必填	含义
teacherChanged	boolean	是	本次更新是否变更老师。

通知只携带课堂公共字段和 teacherChanged，不会返回所有变更配置；完整详情通过课堂查询接口获取。

{
  "eventId": "evt_example_classroom_updated",
  "type": "classroom.updated",
  "appId": "app_example",
  "timestamp": "2026-10-09T02:00:00.000Z",
  "data": {
    "classroomId": "cls_example",
    "name": "数学课堂",
    "status": "pending",
    "teacherEduUserId": "eu_teacher",
    "teacherChanged": false
  }
}

课堂开课

classroom.started

课堂从未开课状态进入 live 后发送。可用于更新业务课程状态或启动课中流程。

data 附加字段	类型	必填	含义
fromStatus	string	是	开课前的课堂状态。
source	string	是	开课来源，见下方取值。
startsAt / endsAt	string	否	计划起止时间，ISO 8601。
actualStartedAt	string	否	实际开课时间，ISO 8601。
effectiveEndsAt	string	否	按实际开课、课时和拖堂计算的结束时间，ISO 8601。

source 取值：create_immediate（创建即开课）、manual（手动）、auto_reconcile（状态协调）、auto_job（定时任务）、lazy_refresh（查询时刷新）。时间字段有值时才发送。通知不代表客户端 IM、RTC 和白板均已就绪。

{
  "eventId": "evt_example_classroom_started",
  "type": "classroom.started",
  "appId": "app_example",
  "timestamp": "2026-10-09T02:00:00.000Z",
  "data": {
    "classroomId": "cls_example",
    "name": "数学课堂",
    "status": "live",
    "teacherEduUserId": "eu_teacher",
    "fromStatus": "pending",
    "source": "manual",
    "startsAt": "2026-10-09T02:00:00.000Z",
    "endsAt": "2026-10-09T03:00:00.000Z",
    "actualStartedAt": "2026-10-09T02:00:00.000Z",
    "effectiveEndsAt": "2026-10-09T03:00:00.000Z"
  }
}

课堂结束

classroom.ended

已开课课堂手动结课或被自动结束后发送。可用于结束业务课中状态和后续归档。

data 附加字段	类型	必填	含义
fromStatus	string	否	结束前状态；批量结束路径可省略。

当前事件不包含出勤统计、录制地址或实际结束时间字段。不要将通知投递时间直接作为课程统计结果。

{
  "eventId": "evt_example_classroom_ended",
  "type": "classroom.ended",
  "appId": "app_example",
  "timestamp": "2026-10-09T02:00:00.000Z",
  "data": {
    "classroomId": "cls_example",
    "name": "数学课堂",
    "status": "ended",
    "teacherEduUserId": "eu_teacher",
    "fromStatus": "live"
  }
}

未开课课堂过期

classroom.expired

未开课课堂到达服务端过期条件、状态变为 expired 后发送。可用于标记该预约课堂已失效。

data 附加字段	类型	必填	含义
fromStatus	string	否	过期前状态；批量过期路径可省略。

该事件与已开课后的 classroom.ended 含义不同。通知不包含过期原因枚举或重新预约结果。

{
  "eventId": "evt_example_classroom_expired",
  "type": "classroom.expired",
  "appId": "app_example",
  "timestamp": "2026-10-09T02:00:00.000Z",
  "data": {
    "classroomId": "cls_example",
    "name": "数学课堂",
    "status": "expired",
    "teacherEduUserId": "eu_teacher",
    "fromStatus": "pending"
  }
}

成员上下台

classroom.stage_changed

成员在占席 on 与非占席状态之间切换后发送。可用于同步台上成员或记录上下台行为。

data 附加字段	类型	必填	含义
action	string	是	on：上台；off：下台。
eduUserId	string	是	发生变化的成员 ID。
role	string	是	成员在本课堂中的角色。
fromStageStatus / stageStatus	string	是	变更前后状态：off、hand_raised、on。
actorEduUserId	string	否	已知操作发起人时返回。
source	string	是	变化来源，见下方取值。
onStageCount	number	是	变化后的台上人数，整数。

source 取值：invite、accept_hand、join、fill_on_start、backfill、leave_stage、leave_classroom、roster_removed、trtc_exit、im_offline、im_timeout。举手、取消或拒绝举手不会产生此事件。join 只表示进课导致占席变化，并非所有成员进课通知。

{
  "eventId": "evt_example_classroom_stage_changed",
  "type": "classroom.stage_changed",
  "appId": "app_example",
  "timestamp": "2026-10-09T02:00:00.000Z",
  "data": {
    "classroomId": "cls_example",
    "name": "数学课堂",
    "status": "live",
    "teacherEduUserId": "eu_teacher",
    "action": "on",
    "eduUserId": "eu_student",
    "role": "student",
    "fromStageStatus": "hand_raised",
    "stageStatus": "on",
    "actorEduUserId": "eu_teacher",
    "source": "accept_hand",
    "onStageCount": 2
  }
}

课件公共字段

四类课件事件的 data 使用下列字段，各事件的附加参数在对应小节列出。

字段	类型	必填	含义
coursewareId	string	是	课件 ID
name	string	是	课件名称
format	string	是	文件格式，例如 pdf
status	string	是	queued、processing、ready、failed
progress	number	是	转码进度，0–100
ownerEduUserId	string	否	记录中的课件所有者 ID
jobId	string	否	已有转码任务时的任务 ID
errorCode / errorMessage	string	否	记录中的错误码与说明
resultManifestUrl	string	否	已有转码结果时的 manifest 地址
coursewareBaseUrl	string	否	已有转码结果时的资源根地址

只有创建事件附加课堂绑定 ID，不应要求后续转码事件均携带该字段。

课件创建

courseware.created

课件主记录入库后发送。可用于关联上传任务与课件 ID。

data 附加字段	类型	必填	含义
fromStatus	string	是	固定为 queued。
classroomId	string	否	创建时指定绑定的课堂。

本事件固定使用 status: queued、progress: 0 的创建快照。即使紧接着转码失败，也先产生本事件，再产生独立的失败事件。

{
  "eventId": "evt_example_courseware_created",
  "type": "courseware.created",
  "appId": "app_example",
  "timestamp": "2026-10-09T02:00:00.000Z",
  "data": {
    "coursewareId": "cw_example",
    "name": "lesson.pdf",
    "format": "pdf",
    "status": "queued",
    "ownerEduUserId": "eu_teacher",
    "progress": 0,
    "fromStatus": "queued",
    "classroomId": "cls_example"
  }
}

课件开始转码

courseware.processing

创建、重试或转码状态更新使课件进入 processing 后发送。可用于显示转码中状态。

data 附加字段	类型	必填	含义
fromStatus	string	是	变更前状态；重试时可以为 failed。

同为 processing 时的进度变化不会逐次产生通知。重试不会重新发送 courseware.created。

{
  "eventId": "evt_example_courseware_processing",
  "type": "courseware.processing",
  "appId": "app_example",
  "timestamp": "2026-10-09T02:00:00.000Z",
  "data": {
    "coursewareId": "cw_example",
    "name": "lesson.pdf",
    "format": "pdf",
    "status": "processing",
    "ownerEduUserId": "eu_teacher",
    "progress": 0,
    "jobId": "job_example",
    "fromStatus": "queued"
  }
}

课件转码完成

courseware.ready

转码结果使课件进入 ready 后发送。可用于刷新课件可用状态和资源入口。

data 附加字段	类型	必填	含义
fromStatus	string	是	进入 ready 前的状态。

资源地址由转码结果提供，有值时才包含。课堂绑定信息需另行查询，不保证带 classroomId。资源 URL 仍需按其访问权限和有效期处理。

{
  "eventId": "evt_example_courseware_ready",
  "type": "courseware.ready",
  "appId": "app_example",
  "timestamp": "2026-10-09T02:00:00.000Z",
  "data": {
    "coursewareId": "cw_example",
    "name": "lesson.pdf",
    "format": "pdf",
    "status": "ready",
    "ownerEduUserId": "eu_teacher",
    "progress": 100,
    "jobId": "job_example",
    "fromStatus": "processing",
    "resultManifestUrl": "https://assets.example.com/courseware/manifest.json",
    "coursewareBaseUrl": "https://assets.example.com/courseware/"
  }
}

课件转码失败

courseware.failed

启动转码失败或转码结果使课件进入 failed 后发送。可用于展示失败信息并决定是否重试。

data 附加字段	类型	必填	含义
fromStatus	string	是	失败前状态，可能为 queued 或 processing 等。

errorCode、errorMessage 有记录时才携带；不要按示例文案匹配业务分支。启动失败时可能没有 jobId。

{
  "eventId": "evt_example_courseware_failed",
  "type": "courseware.failed",
  "appId": "app_example",
  "timestamp": "2026-10-09T02:00:00.000Z",
  "data": {
    "coursewareId": "cw_example",
    "name": "lesson.pdf",
    "format": "pdf",
    "status": "failed",
    "ownerEduUserId": "eu_teacher",
    "progress": 0,
    "fromStatus": "queued",
    "errorMessage": "Conversion could not be started."
  }
}

预留事件

下列事件为订阅目录预留项，暂不发送通知。

目录项	名称对应的含义	当前投递状态
edu_user.registered	用户注册	不产生通知
classroom.member_added	添加课堂成员	不产生通知
classroom.joined	用户进入课堂	不产生通知
classroom.permission_granted	授予课堂权限	不产生通知
classroom.permission_revoked	撤销课堂权限	不产生通知
classroom.feature_status_changed	课堂功能状态变化	不产生通知

media.im_callback、media.trtc_callback、media.live_callback 是内部媒体事件，不在客户订阅目录。客户端回调见客户端 API 与事件。

回调中的用户标识、课堂名称和资源地址需要纳入接收方的信息处理清单，见信息采集清单。