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

概述
说明：
实时互动-教育版提供服务回调，支持将业务的状态通知回调至业务方，帮助业务方实现课前、课中以及课后的统计需求。
﻿
﻿
﻿
1. 回调地址配置。
通过控制台 应用管理 中操作字段下的应用配置回调配置，完成回调地址（Callback）的配置。
﻿
2. 用户可以通过 获取房间事件接口 主动拉取房间事件。该接口仅支持房间结束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 的午夜）开始所经过的秒数。例如：
Go
Java
Python3
package main
﻿
import (
    "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 string
str2hash = "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-8
Accept: 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 OK
﻿
HTTP 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
示例
{
    "Timestamp":1679279225,
    "ExpireTime":1679279825,
    "Sign":"6fcaf48026fe9***************8ede",
    "SdkAppId":35***71,
    "EventType":"MemberJoin",
    "EventData":{
        "RoomId":366317280,
        "UserId":"2Lzh8d3R***************DiDn"
    }
}
成员退出事件
事件类型
MemberQuit
事件说明
当成员退出房间时发出通知。
数据字段
字段名
类型
描述
RoomId
Integer
房间 ID
UserId
String
用户 ID
Reason
Integer
退出原因，详细见下表 Reason 枚举值。
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
    }
}
文档转码完成事件
事件类型
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
事件说明
当伪直播开始时发出通知。
数据字段
字段名
类型
描述
RoomId
Integer
房间 ID
示例
{
    "Timestamp":1679281184,
    "ExpireTime":1679281784,
    "Sign":"964ff6d946328***************3be9",
    "SdkAppId":35***71,
    "EventType":"FakeLiveStart",
    "EventData":{
        "RoomId":324896216
    }
}
伪直播结束事件
事件类型
FakeLiveStop
事件说明
当伪直播结束时发出通知。
数据字段
字段名
类型
描述
RoomId
Integer
房间 ID。
Error.Code
String
错误码(正常结束无此字段)。
Error.Message
String
错误描述(正常结束无此字段)。
示例
{
    "Timestamp":1679281184,
    "ExpireTime":1679281784,
    "Sign":"964ff6d946328***************3be9",
    "SdkAppId":35***71,
    "EventType":"FakeLiveStop",
    "EventData":{
        "RoomId":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。
板书截图完成事件
事件类型
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
    }
}
成员开始推流事件
事件类型
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
    }
}
成员停止推流事件
事件类型
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
    }
}
页面录制事件
事件类型
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"
    		}
   	}
}

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

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

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

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

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

监听服务端事件回调

本页目录：

概述

回调签名方法

事件回调协议

事件列表

房间开始事件

事件类型

事件说明

数据字段

房间结束事件

事件类型

事件说明

数据字段

房间过期事件

事件类型

事件说明

数据字段

录制完成事件

事件类型

事件说明

数据字段

成员进入事件

事件类型

事件说明

数据字段

成员退出事件

事件类型

事件说明

数据字段

Reason 枚举值

文档转码完成事件

事件类型

事件说明

数据字段

文档创建事件

事件类型

事件说明

数据字段

文档删除事件

事件类型

事件说明

数据字段

伪直播开始事件

事件类型

事件说明

数据字段

伪直播结束事件

事件类型

事件说明

数据字段

自定义事件

事件类型

事件说明

数据字段

转存开始事件

事件类型

事件说明

数据字段

转存结束事件

事件类型

事件说明

数据字段

房间用量统计事件

事件类型

事件说明

数据字段

板书截图完成事件

事件类型

事件说明

数据字段

成员开始推流事件

事件类型

事件说明

数据字段

成员停止推流事件

事件类型

事件说明

数据字段

页面录制事件