TUICallEngine

最近更新时间:2025-02-25 15:32:13

我的收藏
TUICallEngine API 是音视频通话组件的无 UI 接口,如果 TUICallKit 的交互并不满足您的需求,您可以使用这套 API 根据您的业务需求自定义封装。
由于小程序开发的限制,需要先给 live-pusher 绑定事件,具体请参见 TUICallkit
说明:
为提供更优质的音视频通信能力,原 tuicall-engine-wx 包已正式停止维护,建议开发者迁移至 @tencentcloud/tuicall-engine-wx 新包。
新包对接口进行了优化调整,部分旧版接口不再兼容,同步提供更简洁、稳定的新接口方案。

API 概览

创建实例和事件回调

API
描述
创建 TUICallEngine 实例(静态方法)
销毁 TUICallEngine 实例(静态方法)
on
增加事件监听
off
取消事件监听

通话操作相关接口函数

API
描述
calls
发起 1v1 通话
在群组通话中,邀请其他人加入
join
主动加入当前的群组通话中
accept
接听通话
reject
拒绝通话
hangup
结束通话
切换通话媒体类型,比如视频通话切音频通话

设备控制相关接口函数

API
描述
开启摄像头
关闭摄像头
切换前后摄像头
打开麦克风
关闭麦克风
选择音频播放设备(听筒/扬声器)

其他接口函数

API
描述
设置用户的头像、昵称
设置日志等级
设置美颜级别,支持关闭默认美颜

API 详情

import TUICallEngine, { TUICallEvent, CALL_MEDIA_TYPE } from '@tencentcloud/tuicall-engine-wx';

createInstance

创建 TUICallEngine 的单例。
wx.$TUICallEngine = TUICallEngine.createInstance({
tim,
sdkAppID,
});
说明
参数
类型
说明
是否必传
sdkAppID
Number
SDKAppId 是腾讯云用于区分客户的唯一标识
tim
ChatSDK
TIM 实例

destroyInstance

销毁 TUICallEngine 的单例。
TUICallEngine.destroyInstance();

on

通过 on 方法可以监听 TUICallEngine 所有的事件。
let handleNewInvitationReceived = function(event) {
// 收到邀请
};
wx.$TUICallEngine.on(TUICallEvent.INVITED, handleNewInvitationReceived, this);
说明
参数
类型
说明
是否必传
eventName
TUICallEvent
事件名
handler
Function
事件的回调函数
context
Any
当前执行上下文(this)

off

移除事件监听。
let handleNewInvitationReceived = function(event) {
// 收到邀请
};
wx.$TUICallEngine.off(TUICallEvent.INVITED, handleNewInvitationReceived);
说明
参数
类型
说明
是否必传
eventName
TUICallEvent
事件名
handler
Function
事件的回调函数

login

登录接口。
const params = {
userID: 'john', // 您的用户 ID
userSig: 'xxxx', // 签名
};
let promise = wx.$TUICallEngine.login(params);
promise.then(() => {
//success
}).catch(error => {
console.warn('login error:', error);
});
参数如下表所示:
参数
类型
含义
是否必传
userID
String
当前用户的 ID,字符串类型,只允许包含英文字母(a-z 和 A-Z)、数字(0-9)、连词符(-)和下划线(_)
userSig
String
腾讯云设计的一种安全保护签名,获取方式请参考 如何计算UserSig

logout

登出接口。
let promise = wx.$TUICallEngine.logout();
promise.then(() => {
// logout success
}).catch(error => {
console.warn('logout error:', error);
});

calls

发起单人或多人通话。
注意
离线推送仅适用于终端(Android 或 iOS),Web 和 微信小程序不支持。
import { MEDIA_TYPE } from 'tuicall-engine-wx';
let promise = wx.$TUICallEngine.groupCall({
userIDList: ['user1', 'user2'],
type: CALL_MEDIA_TYPE.AUDIO_CALL,
});
promise.then(() => {
// groupCall success
}).catch(error => {
console.warn('groupCall error:', error);
});
参数如下表所示:
参数
类型
含义
是否必传
userIDList
Array<String>
被呼叫者的 userID 列表
type
通话的媒体类型
chatGroupID
String
与 chat 结合使用时, chat 群组的群ID
timeout
Number
超时时长,单位:秒
roomID
Number
此次通话的音视频房间 ID,目前仅支持数字房间号,后续版本会支持字符串房间号
userData
String
扩展字段: 用于在邀请信令中增加扩展信息

inviteUser

邀请用户加入此次群组通话。
使用场景:一个群组通话中的用户主动邀请其他人时使用。
const userIDList = ['jack', 'john'];
const params = {
userIDList
};
wx.$TUICallEngine.inviteUser(params).then(() => {
// success
}).catch(error => {
console.error('inviteUser error:', error);
});
参数如下表所示:
参数
类型
含义
是否必传
params
Object
邀请参数
params.userIDList
Array<String>
被叫用户的 userID 列表

join

主动加入此次群组通话。
const params = { callId: xxx };
wx.$TUICallEngine.join(params).then(() => {
// success
}).catch(error => {
console.error('join error:', error);
});
参数如下表所示:
参数
类型
含义
是否必传
params
Object
主动加入参数
params.callId
string
此次通话的唯一 ID。

accept

接受当前通话,当您作为被叫方收到 EVENT.INVITED 事件的回调时,可以调用该接口接听来电。
wx.$TUICallEngine.on(TUICallEvent.INVITED, () => {
wx.$TUICallEngine.accept().promise.then(() => {
// accept success
}).catch(error => {
console.warn('accept error:', error);
});
});

reject

拒绝当前通话,当您作为被叫收到 EVENT.INVITED 的回调时,可以调用该函数拒绝来电。
wx.$TUICallEngine.on(TUICallEvent.INVITED, () => {
wx.$TUICallEngine.reject().then(() => {
// reject success
}).catch(error => {
console.warn('reject error:', error);
});
});

hangup

挂断当前通话,当您处于通话中,可以调用该函数结束通话。
wx.$TUICallEngine.hangup().then(() => {
// hangup success
}).catch(error => {
console.warn('hangup error:', error);
});

switchCallMediaType

当前通话类型切换。
仅支持 1v1 通话过程中使用
wx.$TUICallEngine.switchCallMediaType(MEDIA_TYPE.VIDEO).then(() => {
// switchCallMediaType success
}).catch(error => {
console.warn('switchCallMediaType error:', error);
});
参数如下表所示:
参数
类型
含义
是否必传
type
通话的媒体类型 MEDIA_TYPE.AUDIO:语音通话 MEDIA_TYPE.VIDEO:视频通话

openCamera

您可以调用该函数开启摄像头。
wx.$TUICallEngine.openCamera().then(() => {
// openCamera success
}).catch(error => {
console.warn('openCamera error:', error);
});

closeCamera

您可以调用该函数关闭摄像头,处于通话中的用户会收到回调。
wx.$TUICallEngine.closeCamera().then(() => {
// closeCamera success
}).catch(error => {
console.warn('closeCamera error:', error);
});

switchCamera

切换前后摄像头。
wx.$TUICallEngine.switchCamera().then(() => {
// switchCamera success
}).catch(error => {
console.warn('openMicrophone error:', error);
});

openMicrophone

您可以调用该函数打开麦克风,处于通话中的用户会收到回调。
wx.$TUICallEngine.openMicrophone().then(() => {
// openMicrophone success
}).catch(error => {
console.warn('openMicrophone error:', error);
});

closeMicrophone

您可以调用该函数关闭麦克风,处于通话中的用户会收到回调。
wx.$TUICallEngine.closeMicrophone().then(() => {
// closeMicrophone success
}).catch(error => {
console.warn('closeMicrophone error:', error);
});

selectAudioPlaybackDevice

选择音频播放设备,目前支持听筒、扬声器,在通话场景中,可以使用这个接口来开启/关闭免提模式。
wx.$TUICallEngine.selectAudioPlaybackDevice(AUDIO_PLAYBACK_DEVICE.EAR).then(() => {
// selectAudioPlaybackDevice success
}).catch(error => {
console.warn('selectAudioPlaybackDevice error:', error);
});
参数如下表所示:
参数
类型
含义
是否必传
type
扬声器:AUDIO_PLAYBACK_DEVICE.SPEAKER 听筒:AUDIO_PLAYBACK_DEVICE.EAR

setSelfInfo

设置用户头像、昵称。
wx.$TUICallEngine.setSelfInfo("昵称", "头像 URL").then(() => {
// setSelfInfo success
}).catch(error => {
console.warn('setSelfInfo error:', error);
});
参数如下表所示:
参数
类型
含义
nickName
String
设置昵称
avatar
String
头像地址

setLogLevel

设置日志级别,低于 level 的日志将不会输出。
wx.$TUICallEngine.setLogLevel(level)
参数如下表所示:
参数
含义
level
0
普通级别,日志量较多,接入时建议使用
1
release 级别,SDK 输出关键信息,生产环境时建议使用
2
告警级别,SDK 只输出告警和错误级别的日志
3
错误级别,SDK 只输出错误级别的日志
4
无日志级别,SDK 将不打印任何日志

setBeautyLevel

注意:
≥ v2.1.0 支持
设置美颜级别,支持关闭默认美颜。
wx.$TUICallEngine.setBeautyLevel(beautyLevel: number);
参数如下表所示:
参数
类型
含义
beautyLevel
number
美颜级别,取值范围 0 - 9; 0 表示关闭,9 表示效果最明显

废弃接口

API
描述
call
拨打电话(1v1通话),建议使用 calls 接口。
groupCall
发起群组通话,建议使用 calls 接口。
启动本地画面渲染,建议使用 openCamera。
停止本地画面渲染,建议使用 closeCamera。
主动加入此次群组通话,建议使用 join 接口。

call

拨打电话(1v1通话)。
注意:
离线推送仅适用于终端(Android 或 iOS),Web 和 微信小程序不支持。
let promise = wx.$TUICallEngine.call({
userID: 'user1',
type: MEDIA_TYPE.AUDIO,
});
promise.then(() => {
// call success
}).catch(error => {
console.warn('call error:', error);
});
参数如下表所示:
参数
类型
含义
是否必传
userID
String
被呼叫者的 userID
type
通话的媒体类型
MEDIA_TYPE.AUDIO:语音通话
MEDIA_TYPE.VIDEO:视频通话
roomID
Number
数字房间号, 范围 [1, 2147483647]
userData
String
扩展字段: 用于在邀请信令中增加扩展信息

groupCall

发起群组通话。
注意:
离线推送仅适用于终端(Android 或 iOS),Web 和 微信小程序不支持。
import { MEDIA_TYPE } from 'tuicall-engine-wx';
let promise = wx.$TUICallEngine.groupCall({
userIDList: ['user1', 'user2'],
type: MEDIA_TYPE.AUDIO,
groupID: '123345',
});
promise.then(() => {
// groupCall success
}).catch(error => {
console.warn('groupCall error:', error);
});
参数如下表所示:
参数
类型
含义
是否必传
userIDList
Array<String>
被呼叫者的 userID 列表
type
通话的媒体类型
MEDIA_TYPE.AUDIO:语音通话
MEDIA_TYPE.VIDEO:视频通话
groupID
String
此次群组通话的群 ID
timeout
Number
超时时长,单位:秒
roomID
Number
此次通话的音视频房间 ID,目前仅支持数字房间号,后续版本会支持字符串房间号
userData
String
扩展字段: 用于在邀请信令中增加扩展信息

joinInGroupCall

主动加入此次群组通话。
使用场景:群组内用户主动加入此次群组通话使用。
import { MEDIA_TYPE } from 'tuicall-engine-wx';
const params = {
roomID: 123,
type: MEDIA_TYPE.AUDIO,
groupID: 111
};
wx.$TUICallEngine.joinInGroupCall(params).then(() => {
// success
}).catch(error => {
console.error('joinInGroupCall error:', error);
});
参数如下表所示:
参数
类型
含义
是否必传
params
Object
主动加入参数
roomID
Number
此次通话的音视频房间 ID,目前仅支持数字房间号,后续版本会支持字符串房间号
groupID
String
此次群组通话的群 ID
type
通话的媒体类型
MEDIA_TYPE.AUDIO:语音通话
MEDIA_TYPE.VIDEO:视频通话