Docs Overview/
Call/
Web/
客户端 API/
Engine APIs/
TUICallEvent/

TUICallEvent

TUICallEvent API 简介

TUICallEvent API 是音视频通话组件的事件接口。

事件列表

EVENT
描述
通话过程中错误事件
SDK 进入 ready 状态时收到该事件
用户重复登录，被踢下线
xxxx 用户接通的事件
xxxx 用户加入通话的事件
xxxx 用户离开通话的事件
xxxx 用户拒绝通话的事件
xxxx 用户不响应的事件
xxxx 用户忙线的事件
xxxx 用户是否有视频流的事件
xxxx 用户是否有音频流的事件
所有用户音量大小的反馈事件
群聊更新邀请列表收到该事件
通话接通的事件，v1.4.6+ 支持
通话请求的事件， 后续废弃，建议使用 TUICallEvent.ON_CALL_RECEIVED
通话请求的事件，v1.4.6+ 支持
通话取消的事件， 后续废弃，建议使用 TUICallEvent.ON_CALL_CANCELED
通话取消的事件，v1.4.6+ 支持
通话接通时抛出的事件
通话结束的事件
设备列表更新的事件
通话的媒体类型发生改变的回调
所有用户网络质量的事件，v3.0.7+ 支持

ERROR

通话过程中错误事件，可以通过监听该事件，捕获通话过程中的内部错误。
let onError = function(error) {
  console.log(error.code, error.msg);
};
tuiCallEngine.on(TUICallEvent.ERROR, onError);
参数如下表所示：
参数
类型
含义
code
Number
错误码
msg
String
错误信息

SDK_READY

TUICallEngine 依赖 @tencentcloud/chat SDK，登录成功后才会出发 SDK_READY 事件，然后才能使用 SDK 的各项功能。
let onSDKReady = function(event) {
  console.log(event);
};
tuiCallEngine.on(TUICallEvent.SDK_READY, onSDKReady);

KICKED_OUT

当前用户被踢下线，此时可以 UI 提示用户，并再次重新调用登录。
let handleOnKickedOut = function(event) {
  console.log(event);
};
tuiCallEngine.on(TUICallEvent.KICKED_OUT, handleOnKickedOut);

USER_ACCEPT

如果有用户接通，其他用户都会抛出该事件，userID 就是接通的用户名。
1. 1v1 通话下：被叫接通，主叫会抛出该事件。
2. 群组通话下：A 呼叫 B/C，B 接通，A/C 都会抛出该事件，事件的 userID 都是 B。同理 C 接通，A、B 都会抛出该事件，事件的 userID 都是 C。
let handleUserAccept = function(event) {
  console.log(event.userID);
};
tuiCallEngine.on(TUICallEvent.USER_ACCEPT, handleUserAccept);
参数如下表所示：
参数
类型
含义
userID
String
接通通话的用户 ID

USER_ENTER

如果有用户进入通话，其他用户都会抛出该事件，userID 就是进入通话的用户名。
let handleUserEnter = function(event) {
  console.log(event.userID);
};
tuiCallEngine.on(TUICallEvent.USER_ENTER, handleUserEnter);
参数如下表所示：
参数
类型
含义
userID
String
进入通话的用户 ID

USER_LEAVE

有用户离开此次通话时，通话中的其他用户都会抛出该事件，userID 就是离开通话的用户名。
let handleUserLeave = function(event) {
  console.log(event.userID);
};
tuiCallEngine.on(TUICallEvent.USER_LEAVE, handleUserLeave);
参数如下表所示：
参数
类型
含义
userID
String
离开当前通话的用户 ID

REJECT

通话被拒绝时抛出该事件
1. 在 1v1 通话中，只有主叫方会收到拒绝事件，userID 就是被叫用户名。
2. 在群组通话中，当有被邀请者拒绝通话时，群组通话的其他人都会抛出该事件，userID 就是拒绝通话的用户名。
let handleInviteeReject = function(event) {
  console.log(event.userID);
};
tuiCallEngine.on(TUICallEvent.REJECT, handleInviteeReject);
参数如下表所示：
参数
类型
含义
userID
String
拒绝通话的用户 ID

NO_RESP

被呼叫者没有回应时，其他通话用户都会抛出该事件。
在 1v1 通话中，只有主叫方会抛出无人应答的事件。例如 A 邀请 B，B 不应答，A 抛出该事件。
在群组通话中，当有被邀请者不回应时，群组通话的其他人都会抛出该事件。例如 A 邀请 B、C 进入通话，B 不应答，A、C 均会抛出该事件。
let handleNoResponse = function(event) {
console.log(event.sponsor, event.userIDList);
};
tuiCallEngine.on(TUICallEvent.NO_RESP, handleNoResponse);
参数如下表所示：
参数
类型
含义
sponsor
String
发起方的用户 ID
userIDList
Array<String>
无响应的用户 ID 列表

LINE_BUSY

通话忙线事件。例如：B 正在通话时，此时 A 呼叫 B，A 会抛出事件。
let handleLineBusy = function(event) {
  console.log(event);
};
tuiCallEngine.on(TUICallEvent.LINE_BUSY, handleLineBusy);
参数如下表所示：
参数
类型
含义
userID
String
忙线用户 ID

USER_VIDEO_AVAILABLE

视频通话中一个用户开启/关闭了摄像头, 通话的其他用户都会抛出该事件。例如：A 和 B 在进行视频通话，A 开/关摄像头，B 会抛出该事件。
let handleUserVideoChange = function(event) {
  console.log(event.userID, event.isVideoAvailable);
};
tuiCallEngine.on(TUICallEvent.USER_VIDEO_AVAILABLE, handleUserVideoChange);
参数如下表所示：
参数
类型
含义
userID
String
开/关摄像头的用户 ID
isVideoAvailable
Boolean
true 用户打开摄像头；false 用户关闭摄像头

USER_AUDIO_AVAILABLE

音视频通话中一个用户开启/关闭了麦克风, 通话的其他用户都会抛出该事件。例如：A 和 B 在进行音视频通话，A 开/关麦克风，B 会抛出该事件。
let handleUserAudioChange = function(event) {
  console.log(event.userID, event.isAudioAvailable);
};
tuiCallEngine.on(TUICallEvent.USER_AUDIO_AVAILABLE, handleUserAudioChange);
参数如下表所示：
参数
类型
含义
userID
String
开/关麦克风的用户 ID
isAudioAvailable
Boolean
true 用户打开麦克风；false 用户关闭麦克风

USER_VOICE_VOLUME

音视频通话中用户音量变化时，通话的其他用户都会抛出该事件。例如：A 和 B 在进行音视频通话，A 音量变化，B 会抛出该事件。
let handleUserVoiceVolumeChange = function(event) {
  console.log(event.volumeMap);
};
tuiCallEngine.on(TUICallEvent.USER_VOICE_VOLUME, handleUserVoiceVolumeChange);
参数如下表所示：
参数
类型
含义
volumeMap
Array<Object>
音量表，根据每个 userid 可以获取对应的音量大小，音量范围：[0, 100]

GROUP_CALL_INVITEE_LIST_UPDATE

群聊更新邀请列表收到该事件。
let handleGroupInviteeListUpdate = function(event) {
  console.log(event.userIDList);
};
tuiCallEngine.on(TUICallEvent.GROUP_CALL_INVITEE_LIST_UPDATE, handleGroupInviteeListUpdate);
参数如下表所示：
参数
类型
含义
userIDList
Array<String>
群组更新邀请列表

INVITED

收到一个新的来电请求事件，被叫会收到，您可以通过监听这个事件，来决定是否显示通话接听界面。
注意：
计划后续版本废弃，建议使用：ON_CALL_RECEIVED。

ON_CALL_RECEIVED

收到一个新的来电请求事件，被叫会收到，您可以通过监听这个事件，来决定是否显示通话接听界面。
注意：
v1.4.6+ 版本支持。
let handleOnCallReceived = function(event) {
    console.log(event);
};
tuiCallEngine.on(TUICallEvent.ON_CALL_RECEIVED, handleOnCallReceived);
参数如下表所示：
参数
类型
含义
sponsor
String
邀请者
userIDList
Array<String>
同时还被邀请的人
isFromGroup
Boolean
是否是群组通话
inviteData
Object
呼叫数据
inviteID
String
邀请 ID，标识一次邀请
userData
String
扩展字段：用于在邀请信令中增加扩展信息
callId
String
本次通话的唯一 ID
roomID
Number
此次通话的音视频房间 ID
callMediaType
Number
通话的媒体类型，视频通话、语音通话
callRole
String
角色，枚举类型：主叫、被叫

CALLING_CANCEL

如果通话未建立，都会抛出该事件。您可以通过监听该事件来实现类似未接来电、重置 UI 状态等显示逻辑。通话未建立的场景如下：
注意：
计划后续版本废弃，建议使用：ON_CALL_CANCELED。

ON_CALL_CANCELED

如果通话未建立，都会抛出该事件。您可以通过监听该事件来实现类似未接来电、重置 UI 状态等显示逻辑。通话未建立的场景如下：
主叫取消：主叫抛出该事件，userID 为主叫；被叫也会抛出该事件，userID 为被叫；
被叫超时：主叫会同时抛出 NO_RESP 和 CALLING_CANCEL 事件，userID 为主叫；被叫抛出 CALLING_CANCEL 事件，userID 为被叫；
被叫拒接：主叫会同时抛出 REJECT 和 CALLING_CANCEL 事件，userID 为主叫；被叫抛出 CALLING_CANCEL 事件，userID 为被叫；
被叫忙线：主叫会同时抛出 LINE_BUSY 和 CALLING_CANCEL 事件，userID 为主叫；被叫抛出 CALLING_CANCEL 事件，userID 为被叫；
注意：
v1.4.6+ 版本支持 。
let handleOnCallCanceled = function(event) {
  console.log(event.userID);
};
tuiCallEngine.on(TUICallEvent.ON_CALL_CANCELED, handleOnCallCanceled);
参数如下表所示：
参数
类型
含义
userID
String
通话取消的用户 ID
callId
String
本次通话的唯一 ID
roomID
Number
此次通话的音视频房间 ID
callMediaType
Number
通话的媒体类型，视频通话、语音通话
callRole
String
角色，枚举类型：主叫、被叫

ON_CALL_BEGIN

表示通话接通，主叫和被叫都会抛出该事件，您可以通过监听这个事件来开启云端录制、内容审核等流程。
注意：
v1.4.6+ 版本支持。
let handleOnCallBegin = function(event) {
    console.log(event);
};
tuiCallEngine.on(TUICallEvent.ON_CALL_BEGIN, handleOnCallBegin);
参数如下表所示：
参数
类型
含义
callId
String
本次通话的唯一 ID
roomID
Number
此次通话的音视频房间 ID
callMediaType
Number
通话的媒体类型，视频通话、语音通话
callRole
String
角色，类型：主叫、被叫

CALLING_END

通话结束时，主叫和被叫都会抛出该事件。您可以通过监听这个事件来显示通话时长、通话类型等信息，或者来停止云端的录制流程。
let handleCallingEnd = function(event) {
  console.log(event.userID, event.);
};
tuiCallEngine.on(TUICallEvent.CALLING_END, handleCallingEnd);
参数如下表所示：
参数
类型
含义
roomID
Number
此次通话的音视频房间 ID
callMediaType
Number
通话的媒体类型，视频通话、语音通话
callRole
String
角色，枚举类型：主叫（'inviter'）、被叫（'invitee'）、未知（''）
totalTime
Number
此次通话的时长，单位: 秒
userID
String
通话结束的 userID。
callId
String
本次通话的唯一 ID。v1.4.6+ 版本支持
callEnd
Number
此次通话的时长（后续将废弃，请使用 totalTime），单位: 秒

DEVICED_UPDATED

设备列表更新时抛出该事件。
let handleDeviceUpdated = function({ microphoneList, cameraList, currentMicrophoneID, currentCameraID }) {
  console.log(microphoneList, cameraList, currentMicrophoneID, currentCameraID);
};
tuiCallEngine.on(TUICallEvent.DEVICED_UPDATED, handleDeviceUpdated);

CALL_TYPE_CHANGED

通话类型切换时抛出该事件。
let handleCallTypeChanged = function({ oldCallType, newCallType }) {
  console.log(oldCallType, newCallType);
};
tuiCallEngine.on(TUICallEvent.CALL_TYPE_CHANGED, handleDeviceUpdated);
参数如下表所示：
参数
类型
含义
oldCallType
Number
旧通话类型
newCallType
Number
新通话类型

ON_USER_NETWORK_QUALITY_CHANGED

所有用户网络质量的事件
注意：
v3.0.7+ 支持。
let handleOnUserNetworkQualityChange = function(event) {
  console.log(event.networkQualityList);
};
tuiCallEngine.on(TUICallEvent.ON_USER_NETWORK_QUALITY_CHANGED, handleOnUserNetworkQualityChange);
参数如下表所示：
参数
类型
含义
networkQualityList
Array<Object>
网络状态，根据 userID 可以获取对应用户当前的网络质量（仅表示本地的上下行）。例如： networkQualityList: [{ userId: quality }]。 网络质量说明： quality = 0，网络状况未知 quality = 1，网络状况极佳 quality = 2，网络状况较好 quality = 3，网络状况一般 quality = 4，网络状况差 quality = 5，网络状况极差 quality = 6，网络链接已断开