云服务器特惠 99/年起
  1. 腾讯云优惠网首页
  2. 腾讯云产品

实时互动-教育版 服务端事件回调

• 腾讯云产品

通过控制台 应用管理 中操作字段下的应用配置回调配置，完成回调地址（Callback）的配置。2. 用户可以通过 获取房间事件接口 主动拉取房间事件。该接口仅支持房间结束1小时内拉取，过期房间事件会被释放。

相关产品
实时互动-教育版 产品页，含版本规格、价格与购买入口。

一、概述

注意：说明：

注意：实时互动-教育版提供服务回调，支持将业务的状态通知回调至业务方，帮助业务方实现课前、课中以及课后的统计需求。

1. 回调地址配置。

3. 回调事件列表。

事件类型 事件名称 事件描述
房间事件 RoomStart 房间开始事件。
 RoomEnd 房间结束事件。
 RoomExpire 房间过期事件。
录制事件 RecordFinish 录制完成事件。
成员事件 MemberJoin 成员进入事件。
 MemberQuit 成员退出事件。
文档事件 DocumentTranscodeFinish 文档转码完成事件。
 DocumentCreate 文档创建事件。
 DocumentDelete 文档删除事件。
伪直播事件 FakeLiveStart 伪直播开始。
 FakeLiveStop 伪直播结束。
自定义事件 TaskUpdate 自定义事件。
转存事件 MixedFlowTransferStart 转存开始事件。
 MixedFlowTransferEnd 转存结束事件。
用量统计事件 MemberStatistics 房间用量统计事件。
板书截图事件 WhiteBoardSnapshotFinish 板书截图完成事件。
成员推断流事件 PushStream 成员开始推流事件。
 StopStream 成员停止推流事件。
页面录制事件 WebRecordFinish 页面录制异常结束事件。

二、回调签名方法

注意：回调鉴权服务并非必须，但为了业务安全，建议业务层完成回调的鉴权校验。

对接回调鉴权部分，我们会提供 CallbackKey，用于对回调消息的鉴权。签名算法如下：

Sign = md5(CallbackKey+ExpireTime)示例：CallbackKey = Nj****Ey ExpireTime = 1614151508 Sign = md5(Nj****Ey1614151508) = b9454ab5a85f9***************d34d

其中 ExpireTime 是签名过期时间，如果一条消息通知中的 ExpireTime 值所指定的时间已经过期，则可以判定这条通知无效，进而可以防止网络重放攻击。格式为十进制 UNIX 时间戳，即从1970年01月01日（UTC/GMT 的午夜）开始所经过的秒数。例如：

GoJavaPython3package mainimport ( "crypto/md5" "fmt")func main() { callbackKey := "Nj****Ey" expire := 1614151508 sign := fmt.Sprintf("%x", md5.Sum([]byte(callbackKey+fmt.Sprintf("%d", expire)))) fmt.Printf(fmt.Sprintf("sign:%s", sign)) // sign:b9454ab5a85f9***************d34d}String md5Str = DigestUtils.md5DigestAsHex("NjFGoDEy1614151508".getBytes());# Python 3 code to demonstrate the# working of MD5 (string – hexadecimal) import hashlib # initializing stringstr2hash = "Nj****Ey1614151508"result = hashlib.md5(str2hash.encode()) # printing the equivalent hexadecimal value.print("sign:", end ="")print(result.hexdigest()) #sign:b9454ab5a85f9***************d34d

在你收到回调请求时，会携带 ExpireTime 和 Sign 参数，你可以依据这两个值和回调密钥进行计算校验请求来源的正确性。

三、事件回调协议

我们会向注册的回调地址发起事件回调的形式是 HTTP POST 请求，请求体为 JSON 格式，内容为：

参数名称 类型 描述
Timestamp Integer 事件生成的 Unix 时间戳，单位秒。
ExpireTime Integer 签名的过期时间的 Unix 时间戳，单位秒，如果当前时间晚于过期时间，后台可以判断该请求不合法。
Sign String 回调签名，可以根据事件回调鉴权中描述的方法校验签名是否匹配以校验该请求来源是否合法。
SdkAppId Integer 本次事件所属的应用。
EventType String 详见各回调类型描述。
EventData JSON 详见各回调类型描述。

回调事件示例POST xxxxxxxxxxxxxxx(user-callback-url)Content-Type: application/json; charset=utf-8Accept: application/json{ "Timestamp":1679279232, "ExpireTime":1679279832, "Sign":"fbfd23733e626***************bc29", // 参考 回调签名方法 "SdkAppId":35***71, "EventType":"RoomStart", "EventData":{ "RoomId":366317280 }}

我们会根据回调结果判断是否重试回调，回调应答HTTP状态200即为成功。

回调应答示例应答：HTTP STATUS CODE = 200，客户应答内容可携带 JSON： {"error_code":0}HTTP STATUS CODE 200 OKHTTP BODY:{ "error_code":0}

五、房间开始事件

事件类型

RoomStart

事件说明

当房间开始时发出通知。

数据字段

字段名 类型 描述
RoomId Integer 房间 ID。

示例{ "Timestamp":1679279232, "ExpireTime":1679279832, "Sign":"fbfd23733e626***************bc29", "SdkAppId":35***71, "EventType":"RoomStart", "EventData":{ "RoomId":366317280 }}

六、房间结束事件

事件类型

RoomEnd

事件说明

当房间结束时发出通知。以下情况会触发结束房间。

字段描述 说明
EndReasonctient=0 老师/助教手动操作下课，结束课堂。
EndReasonApi=1 通过云 API 结束课堂。
EndReasonTimeOut= 2 到了下课时间结束课堂。此类情况仅针对：预约下课时间不可拖堂或明确拖堂时间的课堂。
EndReasonNoOnline = 3 房间内无人超时结束课堂。
EndReasonFakeLiveStop =4 伪直播课堂推流结束，自动结束课堂。

数据字段

字段名 类型 描述
RoomId Integer 房间 ID。

示例{ "Timestamp":1679279195, "ExpireTime":1679279795, "Sign":"696560af8fec9***************6448", "SdkAppId":35***71, "EventType":"RoomEnd", "EventData":{ "RoomId":311601250 }}

七、房间过期事件

事件类型

RoomExpire

事件说明

当房间过期时发出通知。

数据字段

字段名 类型 描述
RoomId Integer 房间 ID。

示例{ "Timestamp":1679282220, "ExpireTime":1679282820, "Sign":"07e504e36a373***************0d3c", "SdkAppId":35***71, "EventType":"RoomExpire", "EventData":{ "RoomId":310096990 }}

八、录制完成事件

事件类型

RecordFinish

事件说明

当录制完成生成下载地址时发出通知。

数据字段

字段名 类型 描述
RoomId Integer 房间 ID。
Duration Integer 录制时长，单位秒。
RecordUrl String 录制地址（协议为 https）。
RecordSize Integer 录制文件大小，单位 bit。

示例{ "Timestamp":1679279203, "ExpireTime":1679279803, "Sign":"7ada1f46f27ce***************e094", "SdkAppId":35***71, "EventType":"RecordFinish", "EventData":{ "Duration":63, "RecordSize":698472, "RecordUrl":"https://xxxxxxx.vod2.myqcloud.com/xxxx/xxxxxxx/f0.mp4", "RoomId":311601250 }}

九、成员进入事件

事件类型

MemberJoin

事件说明

当成员进入房间时发出通知。

数据字段

字段名 类型 描述
RoomId Integer 房间 ID。
UserId String 用户 ID。
Role Integer 角色。枚举值：0： 学生。1： 老师。2： 助教。3： 巡课/督导。示例值：0

示例{ "Timestamp":1679279225, "ExpireTime":1679279825, "Sign":"6fcaf48026fe9***************8ede", "SdkAppId":35***71, "EventType":"MemberJoin", "EventData":{ "RoomId":366317280, "UserId":"2Lzh8d3R***************DiDn", "Role":0 }}

十、成员退出事件

事件类型

MemberQuit

事件说明

当成员退出房间时发出通知。

数据字段

字段名 类型 描述
RoomId Integer 房间 ID。
UserId String 用户 ID。
Reason Integer 退出原因，详细见下表 Reason 枚举值。
Role Integer 角色枚举值：0： 学生。1： 老师。2： 助教。3： 巡课/督导。示例值：0

Reason 枚举值

值 描述
0 主动退出。
1 被踢。
2 永久被踢。
4 失去心跳下线。
5 房间结束，成员自动退出。

示例{ "Timestamp":1679279260, "ExpireTime":1679279860, "Sign":"03d41254d4ba7***************3d99", "SdkAppId":35***71, "EventType":"MemberQuit", "EventData":{ "RoomId":397322814, "UserId":"2NG5xjpn***************1TPf", "Reason":0, "Role":1 }}

十一、文档转码完成事件

事件类型

DocumentTranscodeFinish

事件说明

当文档转码完成（成功或失败）时发出通知。

数据字段

字段名 类型 描述
DocumentId String 文档 ID。
State Integer 文档状态。
Result String 转码结果，如果成功则为转码后地址，如果失败则为错误码。
Info String 转码信息。
Thumbnail String 缩略图地址，PPT 缩略图一般有多页，第一页的地址为 thumbnail_url/1.jpg。

示例{ "Timestamp":1679281156, "ExpireTime":1679281756, "Sign":"1597c5c8aaafb***************e780", "SdkAppId":35***71, "EventType":"DocumentTranscodeFinish", "EventData":{ "DocumentId":"sixkzoak", "Info":"", "Result":"https://xxx.cos.ap-shanghai.myqcloud.com/doc/xxxxxx/picture/", "State":3, "Thumbnail":"https://xxxxx.cos.ap-shanghai.myqcloud.com/doc/xxxxx/thumbnail/" }}

十二、文档创建事件

事件类型

DocumentCreate

事件说明

当客户端文档创建成功时发出通知。

数据字段

字段名 类型 描述
DocId String 文档 ID。
DocName String 文档名称。
Owner String 文档拥有者的 UserId。
DocSize Integer 文档大小 单位字节。
DocUrl String 文档链接。
Permission Integer 文档权限。 0：私有文档；1：公共文档。

示例{ "Timestamp":1679281150, "ExpireTime":1679281750, "Sign":"44f0a2e422ede***************f51c", "SdkAppId":35***71, "EventType":"DocumentCreate", "EventData":{ "DocId":"sixkzoak", "DocName":"test.pdf", "DocSize":4162606, "DocUrl":"https://xxxx.cos.ap-shanghai.myqcloud.com/uploads/xxxxx/xxxxxx/xxxxxx.pdf", "Owner":"2Lzh8d3R***************DiDn", "Permission":0 }}

十三、文档删除事件

事件类型

DocumentDelete

事件说明

当客户端文档删除成功时发出通知。

数据字段

字段名 类型 描述
DocId String 文档 ID。

示例{ "Timestamp":1679281184, "ExpireTime":1679281784, "Sign":"964ff6d946328***************3be9", "SdkAppId":35***71, "EventType":"DocumentDelete", "EventData":{ "DocId":"sixkzoak" }}

十四、伪直播开始事件

事件类型

FakeLiveStart

事件说明

当伪直播开始时发出通知。

数据字段

字段名 类型 描述
class_id Integer 房间 ID。

示例{ "Timestamp":1679281184, "ExpireTime":1679281784, "Sign":"964ff6d946328***************3be9", "SdkAppId":35***71, "EventType":"FakeLiveStart", "EventData":{ "class_id":324896216 }}

十五、伪直播结束事件

事件类型

FakeLiveStop

事件说明

当伪直播结束时发出通知。

数据字段

字段名 类型 描述
class_id Integer 房间 ID。
error.code String 错误码（正常结束无此字段）。
error.message String 错误描述（正常结束无此字段）。

示例{ "Timestamp":1679281184, "ExpireTime":1679281784, "Sign":"964ff6d946328***************3be9", "SdkAppId":35***71, "EventType":"FakeLiveStop", "EventData":{ "class_id":324896216, "error":{ "code":"streamInterruption", "message":"streamInterruption" } }}

十六、自定义事件

事件类型

TaskUpdate

事件说明

在自定义 UI 中调用 JSAPI updateTask，并传入参数 enableCallback = true 时发出通知。

数据字段

字段名 类型 描述
RoomId String 房间 ID。
TaskId String 任务 ID（对应 updateTask 的 taskId 参数，可自定义）。
CustomData String 自定义参数（对应 updateTask 的 content 参数）。

事件示例JS 代码示例{ "Timestamp": 1679281184, "ExpireTime": 1679281784, "Sign": "964ff6d946328***************3be9", "SdkAppId": 35***71, "EventType": "TaskUpdate", "EventData": { "RoomId": "397322814", "TaskId": "your-task-id", "CustomData": "{\\"key1\\":\\"value1\\",\\"key2\\":\\"value2\\"}" }}TCIC.SDK.instance.updateTask( 'your-task-id', // taskId JSON.stringify({ key1: 'value1', key2: 'value2' }), // content -1, // duration false, // createOnly '', // bindingUser true, // enableCallback);

十七、转存开始事件

事件类型

MixedFlowTransferStart

事件说明

当自定义转存开始时发出通知。

数据字段

字段名 类型 描述
RoomId Integer 房间 ID。
TransferStatus.Code String 错误码（TransferSucceed、TransferFailed、UnauthorizedOperation）。
TransferStatus.Message String 错误描述（正常开始无此字段）。

示例{ "Timestamp":1679281184, "ExpireTime":1679281784, "Sign":"964ff6d946328***************3be9", "SdkAppId":35***71, "EventType":"MixedFlowTransferStart", "EventData":{ "RoomId":324896216, "TransferStatus":{ "Code":"TransferSucceed", "Message":"" } }}

十八、转存结束事件

事件类型

MixedFlowTransferEnd

事件说明

当自定义转存结束时发出通知。

数据字段

字段名 类型 描述
RoomId Integer 房间 ID。
TransferDuration Integer 转存文件时长，单位秒。
TransferSize Integer 转存文件大小，单位 M。
TransferFileId String 转存 VOD 文件 fileid。
TransferUrl String 转存 VOD 的地址链接。
RecordUrl String 互动课堂侧的录制文件地址。
TransferStatus.Code String 错误码（0、TransferFailed、UnauthorizedOperation）。
TransferStatus.Message String 错误描述。

示例{ "Timestamp": 1679281184, "ExpireTime": 1679281784, "Sign": "964ff6d946328***************3be9", "SdkAppId": 35***71, "EventType": "MixedFlowTransferEnd", "EventData": { "RoomId": 350389385, "TransferDuration": 8, "TransferSize": 6, "TransferFileId": "12***************14", "TransferUrl": "https://1500029853.vod-qcloud.com/6cc0b3e3vodcq1500029853/7792888c1253642697459575214/f0.mp4", "RecordUrl": "https://1500015970.vod2.myqcloud.com/6cac6e5evodcq1500015970/d6c3f4f41253642697457297772/f0.mp4", "TransferStatus": { "Code": "0", "Message": "SUCCESS" } }}

十九、房间用量统计事件

事件类型

MemberStatistics

事件说明

当房间结束时发出通知。

数据字段

字段名 类型 描述
AudienceType Integer 观看类型，互动观看（默认）。
ClassId Integer 课程 ID，同房间 ID。
ClassName String 课程名称，同房间名称。
Interaction Integer TRTC 总时长。
LowLatencyPresent Integer 快直播总时长。
MaxRTCNumber Integer 最大上麦人数。
MemberJoinNumber Integer 进房总次数。
MemberNumber Integer 累计在线人数。
RealEndTime Integer 秒级 Unix 时间戳，实际房间结束时间。
RealStartTime Integer 秒级 Unix 时间戳，实际房间开始时间。
Resolution Integer 头像区域，摄像头视频画面的分辨率。可以有如下取值：1：标清 2：高清 3：全高清
SchoolId Integer 应用 ID，AppId。

20、板书截图完成事件

事件类型

WhiteBoardSnapshotFinish

事件说明

当板书截图生成完毕后发出通知。

数据字段

字段名 类型 描述
RoomId Integer 房间 ID。
Status Integer 板书生成任务的状态。2：失败，3：成功。
Total Integer 截图总数。
Result Array of String 截图列表。

示例{ "Timestamp":1679281184, "ExpireTime":1679281784, "Sign":"964ff6d946328***************3be9", "SdkAppId":35***71, "EventType":"WhiteBoardSnapshotFinish", "EventData":{ "RoomId":324896216, "Result":[ "https://xxx.cos.ap-shanghai.myqcloud.com/snapshot****57037231948620.png", "https://xxx.cos.ap-shanghai.myqcloud.com/snapshot****57037244238347.png" ], "Status":3, "Total":2 }}

21、成员开始推流事件

事件类型

PushStream

事件说明

成员开始推流时发出通知。

注意：目前仅支持直播类型为 “ RTMP 推流直播 ” 房间（创建房间 中 LiveType=2），身份为 “ 老师 ” 的用户开始推流事件的回调。

数据字段

字段名 类型 描述
RoomId Integer 房间 ID。
LiveType Integer 直播类型：0：常规（默认）。1：伪直播。2：RTMP 推流直播。
UserId String 用户 ID。
Role Integer 用户身份：0：学生。1：老师。2：助教。

示例{ "Timestamp":1679281184, "ExpireTime":1679281784, "Sign":"964ff6d946328***************3be9", "SdkAppId":35***71, "EventType":"PushStream", "EventData":{ "RoomId":324896216, "LiveType":2, "UserId":"2Lzh8d3R***************DiDn", "Role":1 }}

22、成员停止推流事件

事件类型

StopStream

事件说明

成员停止推流时发出通知。

注意：目前仅支持直播类型为“RTMP 推流直播”房间（创建房间 中 LiveType=2），身份为“老师”的用户停止推流事件的回调。

数据字段

字段名 类型 描述
RoomId Integer 房间 ID。
LiveType Integer 直播类型：0：常规（默认）。1：伪直播。2：RTMP 推流直播。
UserId String 用户 ID。
Role Integer 用户身份：0：学生。1：老师。2：助教。

示例{ "Timestamp":1679281184, "ExpireTime":1679281784, "Sign":"964ff6d946328***************3be9", "SdkAppId":35***71, "EventType":"StopStream", "EventData":{ "RoomId":324896216, "LiveType":2, "UserId":"2Lzh8d3R***************DiDn", "Role":1 }}

23、页面录制事件

事件类型

WebRecordFinish

事件说明

页面录制出现异常，导致录制自动结束时会发出通知。情况如下：

1. 录制时长达到设定的最大录制时长（24小时）。

2. 录制任务中出现超过最大分辨率限制（1920*1080）的视频或图片。

数据字段

字段名 类型 描述
RoomId Integer 房间 ID。
EventType Integer 状态码804，代表页面录制异常导致结束录制。
EventMessage String Over time limit：录制时长达到设定的最大录制时长，自动结束录制。Over resolution limit：录制任务中出现超过最大分辨率限制的视频源，自动结束录制。

{ "Timestamp":1679281184, "ExpireTime":1679281784, "Sign":"964ff6d946328***************3be9", "SdkAppId":35***71, "EventType":"WebRecordFinish", "EventData":{ "RoomId": 345435412, "EventType": 804, "EventInfo": { "TaskId": "23453323432432", "Payload": { "Status": 1, "EventMessage": "Over time limit" } }}

相关内容：

  1. 实时互动-工业能源版 免注册登录与临时会话授权 通过云 API 接口 修改项目安全模式 开启项目共享密钥，设置32位项目密钥，并根据使用场景设置是否允许自动注册以及远端获取现场设备列表。...
  2. 实时音视频 服务端功能 这篇用于介绍 AI 对话 2.0 服务相关的云 API 接口产生的事件，以 HTTP 请求的形式通知到你的服务器。任务运行期间，TRTC 将 AI 对话过程中的关键事件以回调（Webhook）方式实时推送到业务后端的回调 URL，业务侧无需轮询查询接口即可获取对话内容、状态流转与任务生命周期信息。...
  3. 游戏多媒体引擎 回调说明 受网络影响，你的服务器收到的通知顺序和事件发生的顺序可能不完全一致。 我们的服务有重试机制，但仍不能保证所有的消息都能到达。 考虑到以上两点，不建议你业务的核心业务逻辑依赖消息通知服务。...
  4. 实时音视频 AI 对话服务端回调 这篇用于介绍 AI 服务（AI 实时对话）相关的云 API 接口产生的事件，以 HTTP/HTTPS 请求的形式通知到你的服务器。可以以向腾讯云提供相关的配置信息来开通该服务。你也可以结合TRTC的 房间与媒体回调 使用，实现更多自定义逻辑。...
  5. 实时音视频 AI 实时对话与语音转文字回调 这篇用于介绍 AI 服务（AI 实时对话和 语音转文字功能）相关的云 API 接口产生的事件，以 HTTP/HTTPS 请求的形式通知到你的服务器。可以以向腾讯云提供相关的配置信息来开通该服务。你也可以结合TRTC的 房间与媒体回调 使用，实现更多自定义逻辑。...
  6. 实时互动-教育版 接入准备 这篇档将指导你完成互动课堂（LCIC）的接入准备工作，包括账号注册、应用创建、关键密钥及课堂参数的获取。...
  7. 实时音视频 AI 转录/翻译 2.0 回调事件 这篇针对 TRTC 后台接入 AI 转录/翻译 2.0 的回调事件进行具体说明。...
  8. 实时音视频 新版（2.0）服务端 AI 转录/翻译回调说明 这篇说明TRTC服务端AI转录/翻译回调事件的配置、消息格式、参数含义及签名校验方法，支持四种事件类型并给出超时重试规则。 配置信息：需在TRTC控制台配置回调地址与可选密钥，支持AI转录2.0回调。 事件类型：包括转录开始(1401)、结束(1402)、ASR句子(1403)及翻译句子(1404)四种回调。 签名校验：使用HMAC SHA256算法计算签名，确保回调来源可信。...
赞 (0)
上一篇 4天前
下一篇 4天前