即时通信 IM TUICallKit

TUICallKit 是音视频通话组件的含 UI 接口，使用 TUICallKit API，您可以通过简单接口快速实现一个类微信的音视频通话场景；更详细的接入步骤，详见 快速接入TUICallKit。
说明：
为提供更优质的音视频通信能力，原 @tencentcloud/call-uikit-wechat 包已正式停止维护，建议开发者迁移至 @tencentcloud/call-uikit-wx-uniapp、@tencentcloud/call-uikit-wx 新包。
新包对接口进行了优化调整，部分旧版接口不再兼容，同步提供更简洁、稳定的新接口方案。
API 概览
API
描述
﻿<TUICallKit />﻿
TUICallKit 通话 UI 组件。
﻿init﻿
初始化 TUICallKit
﻿calls﻿
发起单人或多人通话。
﻿join﻿
主动加入通话。
﻿setSelfInfo﻿
设置用户的头像、昵称
﻿setCallingBell﻿
设置自定义来电铃声
﻿setLogLevel﻿
设置日志级别
﻿enableFloatWindow﻿
开启/关闭悬浮窗功能
﻿enableMuteMode﻿
开启/关闭来电铃声
﻿hideFeatureButton﻿
隐藏按钮。
﻿setLocalViewBackgroundImage﻿
设置本地用户通话界面背景图。
﻿setRemoteViewBackgroundImage﻿
设置远端用户通话界面背景图。
﻿setLayoutMode﻿
设置通话界面布局模式。
﻿setCameraDefaultState﻿
设置摄像头是否默认打开。
﻿destroyed﻿
销毁 TUICallKit。
﻿getTUICallEngineInstance﻿
获取 TUICallEngine 实例。
API 详情
uni-app 小程序
微信小程序
import { TUICallKitServer } from "@tencentcloud/call-uikit-wx-uniapp"; 
import { TUICallKitServer } from "@tencentcloud/call-uikit-wx"; 
init
初始化 TUICallKit。
TUICallKitServer.init({
     sdkAppID: 0, // 替换为您自己账号下的 SDKAppId
     userID: 'jane', // 填写当前用的 userID
     userSig: 'xxxxxxxxxxxx',
     tim: null, // 如果您不需要 TIM 实例，可忽略
})
参数如下表所示：
参数
类型
说明
是否必填
sdkAppID
Number
您可以在实时音视频控制台 > 应用管理 > 应用信息中查看 SDKAppID
是
userID
String
当前用户的 ID，字符串类型，只允许包含英文字母（a-z 和 A-Z）、数字（0-9）、连词符（-）和下划线（_）
是
userSig
String
腾讯云设计的一种安全保护签名，获取方式请参见：如何计算及使用 UserSig﻿
是
tim
ChatSDK
TIM 实例
否
这里详细介绍一下 init 中的几个参数：
userSig：使用步骤三中获取的 SecretKey 对 sdkAppID、userID 等信息进行加密，就可以得到 userSig，它是一个鉴权用的票据，用于腾讯云识别当前用户是否能够使用 TRTC 的服务，更多信息请参见 如何计算及使用 UserSig。
tim 可以将外部的 tim 实例通过 init 透传给 callkit ，tim 参数适用于业务中已存在 TIM 实例，为保证 TIM 实例唯一性。
calls
发起群组通话。
TUICallKitServer.calls({
    userIDList: ["jane", "mike", "tommy"],
    type: 1,
})
参数如下表所示：
参数
类型
含义
是否必填
userIDList
Array<String>
目标用户的 userId 列表，示例：["jane", "mike", "tommy"]
是
type
﻿CallMediaType﻿
通话的媒体类型，参数值说明参见 CallMediaType 通话类型﻿
是
chatGroupID
String
与 chat 结合使用时， chat 群组的群ID
是
roomID
Number
数字房间号, 范围 [1, 2147483647]
否
userData
String
扩展字段: 用于在邀请信令中增加扩展信息
否
timeout
Number
通话的超时时间，0 为不超时，单位 s(秒)（选填） ，默认 30s
被叫需要在 30s 内处于登录状态，timeout 值才会有效，具体参见 timeout 字段设置无效﻿
否
﻿offlinePushInfo﻿
Object
自定义离线消息推送（选填）
否
join
发起群组通话。
TUICallKitServer.join({callId: xx});
参数如下表所示：
参数
类型
含义
是否必填
callId
string
此次通话的唯一 ID。
是
setSelfInfo
设置用户头像、昵称。
注意：
通话中使用该接口修改用户信息，UI 不会立即更新，需要等到下次通话才能看到变化。
TUICallKitServer.setSelfInfo({ nickName: "xxx", avatar: "http://xxx" }); 
参数如下表所示：
参数
类型
含义
nickName
String
设置昵称
avatar
String
头像地址
setCallingBell
设置自定义来电铃声。
这里仅限传入本地文件地址，需要确保该文件目录是应用可以访问的。
传入路径应为本地铃声文件的绝对地址。
如需恢复默认铃声，filePath 传空即可。
支持的铃声文件格式：
格式
iOS
Android
m4a
√
√
mp3
√
√
wav
√
√
aac
√
√
TUICallKitServer.setCallingBell("filePath")
参数如下表所示：
参数
类型
含义
filePath
String
铃声地址
setLogLevel
设置日志级别，低于 level 的日志将不会输出。
TUICallKitServer.setLogLevel(level)
参数如下表所示：
参数
值
含义
level
0 
普通级别，日志量较多，接入时建议使用
﻿
1 
release 级别，SDK 输出关键信息，生产环境时建议使用
﻿
2 
告警级别，SDK 只输出告警和错误级别的日志
﻿
3
错误级别，SDK 只输出错误级别的日志
﻿
4 
无日志级别，SDK 将不打印任何日志
enableFloatWindow
开启/关闭悬浮窗功能。
默认为false，通话界面左上角的悬浮窗按钮隐藏，设置为true后显示。
TUICallKitServer.enableFloatWindow(enable?: Boolean)
enableMuteMode
开启/关闭来电铃声。
开启后，收到通话请求时，不会播放来电铃声。
try {
  await TUICallKitServer.enableMuteMode(enable: boolean)
} catch (error: any) {
  console.error(`[TUICallKit] Failed to call the enableMuteMode API. Reason: ${error}`);
}
hideFeatureButton
隐藏功能按钮，目前仅支持 摄像头，麦克风和切换前后置按钮。
TUICallKitServer.hideFeatureButton(buttonName: FeatureButton);
参数列表：
参数
类型
是否必填
含义
buttonName
﻿FeatureButton﻿
是
按钮名称
setLocalViewBackgroundImage
设置本地用户通话背景。
TUICallKitServer.setLocalViewBackgroundImage(url: string);
参数列表：
参数
类型
是否必填
含义
url
string
是
图片地址（支持本地路径和网络地址）
注意：
如果使用网络地址，需要将网络地址添加到 request 合法域名。
setRemoteViewBackgroundImage
设置远端用户通话背景。
TUICallKitServer.setRemoteViewBackgroundImage(userId: string, url: string);
参数列表：
参数
类型
是否必填
含义
userId
string
是
远端用户 userId，设置为 '*' 表示对所有远端用户生效
url
string
是
图片地址（支持本地路径和网络地址）
注意：
如果使用网络地址，需要将网络地址添加到 request 合法域名。
setLayoutMode
设置通话界面布局模式。
import { TUICallKitServer, LayoutMode } from "../../TUICallKit/src/index";
TUICallKitServer.setLayoutMode(LayoutMode.LocalInLargeView);
参数列表：
参数
类型
是否必填
含义
layoutMode
﻿LayoutMode﻿
是
用户流的布局模式
setCameraDefaultState
设置摄像头是否默认打开。
TUICallKitServer.setCameraDefaultState(true);
参数列表：
参数
类型
是否必填
含义
isOpen
boolean
是
是否开启摄像头
destroyed
销毁 TUICallKit。
TUICallKitServer.destroyed()
getTUICallEngineInstance
获取 TUICallEngine 实例。
TUICallKitServer.getTUICallEngineInstance();
TUICallKit 类型定义
offlinePushInfo
参数
类型
是否必填
含义
offlinePushInfo.title
String
否
离线推送标题（选填）
offlinePushInfo.description
String
否
离线推送内容（选填）
offlinePushInfo.androidOPPOChannelID
String
否
离线推送设置 OPPO 手机 8.0 系统及以上的渠道 ID（选填）
offlinePushInfo.extension
String
否
离线推送透传内容（选填）（tsignaling 版本 ≥ 0.9.0）
FeatureButton
FeatureButton 类型
描述
FeatureButton.Camera
摄像头按钮
FeatureButton.Microphone
麦克风按钮
FeatureButton.SwitchCamera
切换前后置摄像头按钮
FeatureButton.InviteUser
邀请他人按钮
LayoutMode
LayoutMode 类型
描述
LayoutMode.LocalInLargeView
本地用户在大窗显示
LayoutMode.RemoteInLargeView
远端用户在大窗显示
废弃接口
call
拨打电话（1v1 通话）。
﻿
TUICallKitServer.call({
    userID: "jane",
    type: 1
})
参数如下表所示：
参数
类型
含义
是否必填
userID
String
被叫用户的 ID
是
type
Number
通话的媒体类型：1：语音通话    2：视频通话
是
roomID
Number
数字房间号, 范围 [1, 2147483647]
否
strRoomID
String
字符串房间号。v3.3.1+ 支持
1. roomID 与 strRoomID 是互斥的，若您选用 strRoomID，则 roomID 需要填写为 0。若两者都填，SDK 将优先选用 roomID。
2. 不要混用 roomID 和 strRoomID，因为它们之间是不互通的，例如数字 123 和字符串 "123" 是两个完全不同的房间。
否
userData
String
扩展字段: 用于在邀请信令中增加扩展信息
否
timeout
Number
通话的超时时间，0 为不超时, 单位 s(秒)（选填） - 默认 30s
被叫需要在 30s 内处于登录状态，timeout 值才会有效，具体参见 timeout 字段设置无效﻿
否
﻿offlinePushInfo﻿
Object
自定义离线消息推送（选填）
否
groupCall
发起群组通话。
TUICallKitServer.groupCall({
    userIDList: ["jane", "mike", "tommy"],
    type: 1,
    groupID: "12345678"
})
参数如下表所示：
参数
类型
含义
是否必填
userIDList
Array<String>
目标用户的 userId 列表，示例：["jane", "mike", "tommy"]
是
type
﻿CallMediaType﻿
通话的媒体类型，参数值说明参见 CallMediaType 通话类型﻿
是
groupID
String
此次群组通话的群 ID
是
roomID
Number
数字房间号, 范围 [1, 2147483647]
否
strRoomID
String
字符串房间号。v3.3.1+ 支持
1. roomID 与 strRoomID 是互斥的，若您选用 strRoomID，则 roomID 需要填写为 0。若两者都填，SDK 将优先选用 roomID。
2. 不要混用 roomID 和 strRoomID，因为它们之间是不互通的，例如数字 123 和字符串 "123" 是两个完全不同的房间。
否
userData
String
扩展字段: 用于在邀请信令中增加扩展信息
否
timeout
Number
通话的超时时间，0 为不超时，单位 s(秒)（选填） ，默认 30s
被叫需要在 30s 内处于登录状态，timeout 值才会有效，具体参见 timeout 字段设置无效﻿
否
﻿offlinePushInfo﻿
Object
自定义离线消息推送（选填）
否
joinInGroupCall
﻿加
入群组中已有的音视频通话。
说明：
加入群组中已有的音视频通话前，需要提前创建或加入IM 群组，并且群组中已有用户在通话中，如果已经创建，请忽略。
群组的创建详见：IM 群组管理，或者您也可以直接使用 IM TUIKIT，一站式集成聊天、通话等场景。
try {
  const params = {
    type: 2, // 视频通话
    groupID: "xxx",
    roomID: 0,
  };
  await TUICallKitServer.joinInGroupCall(params);
} catch (error: any) {
  console.error(`[TUICallKit] Failed to call the enableMuteMode API. Reason: ${error}`);
}
参数列表：
参数
类型
是否必填
含义
type
﻿CallMediaType﻿
是
通话的媒体类型，参数值说明参见 CallMediaType 通话类型﻿
groupID
string
是
此次群组通话的群 ID
roomID
number
是
此次通话的音视频房间 ID

API	描述
<TUICallKit />	TUICallKit 通话 UI 组件。
init	初始化 TUICallKit
calls	发起单人或多人通话。
join	主动加入通话。
setSelfInfo	设置用户的头像、昵称
setCallingBell	设置自定义来电铃声
setLogLevel	设置日志级别
enableFloatWindow	开启/关闭悬浮窗功能
enableMuteMode	开启/关闭来电铃声
hideFeatureButton	隐藏按钮。
setLocalViewBackgroundImage	设置本地用户通话界面背景图。
setRemoteViewBackgroundImage	设置远端用户通话界面背景图。
setLayoutMode	设置通话界面布局模式。
setCameraDefaultState	设置摄像头是否默认打开。
destroyed	销毁 TUICallKit。
getTUICallEngineInstance	获取 TUICallEngine 实例。

参数	类型	说明	是否必填
sdkAppID	Number	您可以在实时音视频控制台 > 应用管理 > 应用信息中查看 SDKAppID	是
userID	String	当前用户的 ID，字符串类型，只允许包含英文字母（a-z 和 A-Z）、数字（0-9）、连词符（-）和下划线（_）	是
userSig	String	腾讯云设计的一种安全保护签名，获取方式请参见：如何计算及使用 UserSig	是
tim	ChatSDK	TIM 实例	否

参数	类型	含义	是否必填
userIDList	Array<String>	目标用户的 userId 列表，示例：["jane", "mike", "tommy"]	是
type	CallMediaType	通话的媒体类型，参数值说明参见 CallMediaType 通话类型	是
chatGroupID	String	与 chat 结合使用时， chat 群组的群ID	是
roomID	Number	数字房间号, 范围 [1, 2147483647]	否
userData	String	扩展字段: 用于在邀请信令中增加扩展信息	否
timeout	Number	通话的超时时间，0 为不超时，单位 s(秒)（选填），默认 30s 被叫需要在 30s 内处于登录状态，timeout 值才会有效，具体参见 timeout 字段设置无效	否
offlinePushInfo	Object	自定义离线消息推送（选填）	否

参数	值	含义
level	0	普通级别，日志量较多，接入时建议使用
		1	release 级别，SDK 输出关键信息，生产环境时建议使用
		2	告警级别，SDK 只输出告警和错误级别的日志
		3	错误级别，SDK 只输出错误级别的日志
		4	无日志级别，SDK 将不打印任何日志

FeatureButton 类型	描述
FeatureButton.Camera	摄像头按钮
FeatureButton.Microphone	麦克风按钮
FeatureButton.SwitchCamera	切换前后置摄像头按钮
FeatureButton.InviteUser	邀请他人按钮

LayoutMode 类型	描述
LayoutMode.LocalInLargeView	本地用户在大窗显示
LayoutMode.RemoteInLargeView	远端用户在大窗显示

TUICallKit

本页目录：

API 概览

API 详情

init

calls

join

setSelfInfo

setCallingBell

setLogLevel

enableFloatWindow

enableMuteMode

hideFeatureButton

setLocalViewBackgroundImage

setRemoteViewBackgroundImage

setLayoutMode

setCameraDefaultState

destroyed

getTUICallEngineInstance

TUICallKit 类型定义

offlinePushInfo

FeatureButton

LayoutMode

废弃接口

call

groupCall

joinInGroupCall