tencent cloud

事件回调服务支持将实时音视频业务下的事件，以 HTTP/HTTPS 请求的形式通知到您的服务器。事件回调服务已集成房间事件组（Room Event）和媒体事件组（Media Event）下的一些事件，您可以向腾讯云提供相关的配置信息来开通该服务。

配置信息

实时音视频 TRTC 控制台支持自助配置回调信息，配置完成后即可接收事件回调通知。详细操作指引请参见 回调配置。

注意：

您需要提前准备以下信息：

• 必要项：接收回调通知的 HTTP/HTTPS 服务器地址。
• 可选项：计算签名的密钥 key，由您自定义一个最大32个字符的 key，以大小写字母及数字组成。

超时重试

事件回调服务器在发送消息通知后，5秒内没有收到您的服务器的响应，即认为通知失败。首次通知失败后会立即重试，后续失败会以10秒的间隔继续重试，直到消息存续时间超过1分钟，不再重试。

事件回调消息格式

事件回调消息以 HTTP/HTTPS POST 请求发送给您的服务器，其中：

• 字符编码格式：UTF-8。
• 请求：body 格式为 JSON。
• 应答：HTTP STATUS CODE = 200，服务端忽略应答包具体内容，为了协议友好，建议客户应答内容携带 JSON： {"code":0}。
• 包体示例：下述为“房间事件组-进入房间”事件的包体示例。
  {
      "EventGroupId": 1,                #房间事件组
      "EventType": 103,                 #进入房间事件
      "CallbackTs": 1615554923704,      #回调时间，单位毫秒
      "EventInfo": {
          "RoomId": 12345,                #数字房间号
          "EventTs": 1615554922,          #事件发生时间，单位秒
          "UserId": "test",               #用户ID
          "UniqueId": 1615554922656,      #唯一标识符
          "Role": 20,                     #用户角色，主播
          "TerminalType": 3,        #终端类型，IOS端
          "UserType": 3,        #用户类型，Native SDK
          "Reason": 1        #进房原因，正常进房
      }
  }

参数说明

回调消息参数

• 事件回调消息的 header 中包含以下字段：

  字段名	值
  Content-Type	application/json
  Sign	签名值
  SdkAppId	sdk application id

• 事件回调消息的 body 中包含以下字段：

  字段名	类型	含义
  EventGroupId	Number	事件组 ID
  EventType	Number	回调通知的事件类型
  CallbackTs	Number	事件回调服务器向您的服务器发出回调请求的 Unix 时间戳，单位为毫秒
  EventInfo	JSON Object	事件信息

事件组 ID

字段名	值	含义
EVENT_GROUP_ROOM	1	房间事件组
EVENT_GROUP_MEDIA	2	媒体事件组

事件类型

字段名	值	含义
EVENT_TYPE_CREATE_ROOM	101	创建房间
EVENT_TYPE_DISMISS_ROOM	102	解散房间
EVENT_TYPE_ENTER_ROOM	103	进入房间
EVENT_TYPE_EXIT_ROOM	104	退出房间
EVENT_TYPE_CHANGE_ROLE	105	切换角色
EVENT_TYPE_START_VIDEO	201	开始推送视频数据
EVENT_TYPE_STOP_VIDEO	202	停止推送视频数据
EVENT_TYPE_START_AUDIO	203	开始推送音频数据
EVENT_TYPE_STOP_AUDIO	204	停止推送音频数据
EVENT_TYPE_START_ASSIT	205	开始推送辅路数据
EVENT_TYPE_STOP_ASSIT	206	停止推送辅路数据

注意：

退出房间只会回调104事件，不会回调202跟204事件。104事件相当于包含了202和204事件。手动关闭视频/音频，才会回调202/204事件。

事件信息

字段名	类型	含义
RoomId	String/Number	房间名（类型与客户端房间号类型一致）
EventTs	Number	事件发生的 Unix 时间戳，单位为秒（兼容保留）
EventMsTs	Number	事件发生的 Unix 时间戳，单位为毫秒
UserId	String	用户 ID
UniqueId	Number	唯一标识符（option：房间事件组携带） 当客户端发生了一些特殊行为，例如切换网络、进程异常退出及重进等，此时您的回调服务器可能会收到同一个用户多次进房和退房回调，UniqueId 可用于标识用户的同一次进退房
Role	Number	角色类型（option：进退房时携带）
TerminalType	Number	终端类型（option：进房时携带）
UserType	Number	用户类型（option：进房时携带）
Reason	Number	具体原因 （option：进退房时携带）

注意：

我们已发布“过滤客户端特殊行为导致的重复回调”策略。如果您是2021年07月30日之后接入回调服务，默认走新策略，房间事件组不再携带 UniqueId（唯一标识符）。

角色类型

字段名	值	含义
MEMBER_TRTC_ANCHOR	20	主播
MEMBER_TRTC_VIEWER	21	观众

终端类型

字段名	值	含义
TERMINAL_TYPE_WINDOWS	1	Windows 端
TERMINAL_TYPE_ANDROID	2	Android 端
TERMINAL_TYPE_IOS	3	iOS 端
TERMINAL_TYPE_LINUX	4	Linux 端
TERMINAL_TYPE_OTHER	100	其他

用户类型

字段名	值	含义
USER_TYPE_WEBRTC	1	webrtc
USER_TYPE_APPLET	2	小程序
USER_TYPE_NATIVE_SDK	3	Native SDK

具体原因

字段名	含义
进房	1：正常进房 2：切换网络 3：超时重试 4：跨房连麦进房
退房	1：正常退房 2：超时离开 3：房间用户被移出 4：取消连麦退房 5：强杀 注意：Android 系统无法捕捉进程被强杀，只能等待后台超时离开，此时回调 reason 为2

计算签名

签名由 HMAC SHA256 加密算法计算得出，您的事件回调接收服务器收到回调消息后，通过同样的方式计算出签名，相同则说明是腾讯云的实时音视频的事件回调，没有被伪造。签名的计算如下所示：

//签名 Sign 计算公式中 key 为计算签名 Sign 用的加密密钥。
Sign = base64（hmacsha256(key, body)）

注意：

body 为您收到回调请求的原始包体，不要做任何转化，示例如下：

>body="{\n\t\"EventGroupId\":\t1,\n\t\"EventType\":\t103,\n\t\"CallbackTs\":\t1615554923704,\n\t\"EventInfo\":\t{\n\t\t\"RoomId\":\t12345,\n\t\t\"EventTs\":\t1608441737,\n\t\t\"UserId\":\t\"test\",\n\t\t\"UniqueId\":\t1615554922656,\n\t\t\"Role\":\t20,\n\t\t\"Reason\":\t1\n\t}\n}"