帮你快速理解、总结文档立即下载

Web

最近更新时间:2026-08-13 14:35:32
我的收藏
说明:
tccc 是加载 SDK 后的全局变量,可直接访问。

通用结构

AgentStatus

座席状态。
字段
描述
free
示闲。
busy
忙碌。
countdown
话后整理。
arrange
话后整理(座席手动点击继续整理)。
notReady
示忙。
rest
小休。

ServerType

端服务类型,描述电话类型会话时使用的端类型。
字段
描述
staffSeat
Web 座席类型。
staffPhoneSeat
座席手机类型。
miniProgramSeat
小程序类型。
staffExtensionSeat
话机类型。

CommonSDKResponse

参数
类型
必填
备注
options
status
'success' |'error'
SDK API 调用结果,成功时返回 success,失败返回 error。
errorMsg
string
错误信息,当 status 为 error 时返回。

Call(电话客服和音频客服相关接口函数)

电话呼出

tccc.Call.startOutboundCall(options): Promise<CallResponse>

参数
类型
必填
备注
options
phoneNumber
String
被叫号码。
phoneDesc
String
号码备注,在通话条中会替代号码显示。
uui
String
用户自定义数据,传入后可通过 电话 CDR 事件 推送返回。
skillGroupId
String
指定技能组内绑定的外呼号码。
callerPhoneNumber
String
指定外呼号码。
servingNumberGroupIds
String[]
指定号码 ID 列表。
phoneEncodeType
'number'
目前仅支持 'number',在开启 号码映射 时强制使用真实号码。
CallResponse 描述如下:
参数
类型
必填
备注
response
sessionId
String
会话 ID。
calleeLocation
String
被叫号码归属地址。
calleePhoneNumber
String
被叫号码。
callerPhoneNumber
String
外呼时使用的主叫号码。
serverType
String
表示外呼时使用的端类型,可选值有:staffSeat,staffPhoneSeat,staffExtensionSeat。详细说明参见 会话服务类型
remark
String
被叫号码备注。

接待会话

tccc.Call.accept(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID,从 tccc.events.callIn 事件中获取。

挂断会话

tccc.Call.hangUp(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID。

删除会话

tccc.Call.deleteCall(options)

参数
类型
必填
备注
options
sessionId
String
会话 ID。

静音

tccc.Call.muteMic(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID。

取消静音

tccc.Call.unmuteMic(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID。

当前是否静音

tccc.Call.isMicMuted(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID。

发起内部通话

tccc.Call.startInternalCall(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
calleeUserId
String
被叫座席账号。
useMobile
Boolean
是否呼叫对方手机。

转接会话

tccc.Call.transfer(options): Promise<CommonSDKResponse>

转接优先级:userId > skillGroupId > phone
参数
类型
必填
备注
options
sessionId
String
会话 ID。
skillGroupId
Number
转接到指定技能组。
userId
String
转接到指定座席。
phone
String
转接到指定号码。

呼叫保持

tccc.Call.hold(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID。

通话监听

tccc.Call.monitor(options): Promise<CommonSDKResponse>

发起通话监听,默认是语音监听,只能同时发起一个。当指定 textOnly: true 时,可同时发起多个文字监听,该参数需开启 实时语音转文字 功能。
说明:
该 API 需管理员或质检员角色才能调用。
参数
类型
必填
备注
options
sessionId
String
被监听的会话 ID,可从 会话信息列表 中获取。
textOnly
Boolean
默认为 false,表示发起语音监听,true 表示发起文字监听。

退出通话监听

tccc.Call.exitMonitor(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID。

强拆

tccc.Call.intercept(options): Promise<CommonSDKResponse>

发起通话强拆,被强拆的会话必须处于被监听状态。
参数
类型
必填
备注
options
sessionId
String
被强拆的会话 ID。

取消通话保持

tccc.Call.unHold(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID。

发送分机号

tccc.Call.sendDigits(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID。
dtmfText
String
需要发送的分机号。

开启 ASR(语音识别功能)

tccc.Call.startASR(options): Promise<CommonSDKResponse>

说明:
使用该方法需要购买语音识别套餐包
参数
类型
必填
备注
options
sessionId
String
会话 ID。

关闭 ASR(语音识别功能)

tccc.Call.stopASR(): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID。

Chat(在线客服相关接口函数)

接听会话

tccc.Chat.accept(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID。

结束会话

tccc.Chat.end(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID。

转接会话

tccc.Chat.transfer(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID。
skillGroupId
String
转接到指定技能组。
userId
String
转接到指定座席。

Video(视频客服相关接口函数)

接听会话

tccc.Video.accept(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID。

挂断会话

tccc.Video.end(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID。

静音

tccc.Video.muteMic(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID。

取消静音

tccc.Video.unmuteMic(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID

关闭摄像头

tccc.Video.muteVideo(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID。

开启摄像头

tccc.Video.unmuteVideo(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID。

转接会话

tccc.Video.transfer(): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
sessionId
String
会话 ID。
skillGroupId
String
转接到指定技能组。
userId
String
转接到指定座席。

Agent(座席状态相关接口函数)

更多座席状态枚举类型请参见 座席状态

上线

tccc.Agent.online(): void

下线

tccc.Agent.offline(): void

设置座席状态

tccc.Agent.setStatus(options): Promise<CommonSDKResponse>

参数
类型
必填
备注
options
status
String
座席状态,可选值:
free:示闲。
rest:小休。
notReady:示忙。
stopNotReady:停止示忙。
restReason
String
小休原因。

获取座席状态

tccc.Agent.getStatus():AgentStatus

Devices(设备相关接口函数)

检测当前浏览器是否支持

tccc.Devices.isBrowserSupported(): boolean

说明:
TCCC Web SDK 支持 Chrome 56、Edge 80以上的浏览器。

返回麦克风设备列表

tccc.Devices.getMicrophones(): Promise<MediaDeviceInfo []>

返回扬声器设备列表

tccc.Devices.getSpeakers(): Promise<MediaDeviceInfo []>

UI(座席界面相关接口函数)

隐藏 SDK 所有 UI

tccc.UI.hide(): void

显示 SDK 所有 UI

tccc.UI.show(): void

显示浮动按钮

tccc.UI.showfloatButton(): void

隐藏浮动按钮

tccc.UI.hidefloatButton(): void

显示工作台

tccc.UI.showWorkbench(): void

隐藏工作台

tccc.UI.hideWorkbench(): void

显示通话条

tccc.UI.showNotificationBar(): void

隐藏通话条

tccc.UI.hideNotificationBar(): void

修改 SDK 本地设置

支持关闭 SDK 铃声和系统通知

tccc.UI.updateUserCustomSettings(settings): void

settings 内参数都是可选项,支持增量更新。
参数
类型
必填
备注
settings
disableRingtone
Boolean
true 表示禁用 SDK 的铃声,包括来电铃声、接听铃声。
disableNotification
Boolean
true 表示禁用 SDK 的系统通知。

Events(事件)

事件监听

tccc.on(event, callback)

取消事件监听

tccc.off(event, callback)

SDK 初始化完成

tccc.events.ready

当 SDK 初始化完成时触发,此时可安全调用 API。
callback 参数
类型
必填
备注
options
tabUUID
String
表示当前页面的唯一 ID,刷新后会变,用于多 Tab 集成 SDK。

会话呼入

tccc.events.callIn

会话呼入类型包括:
phone:电话会话
im:在线会话
voip:音频会话
video:视频会话
internal:内线会话

电话会话呼入

callback 参数
类型
必填
备注
options
sessionId
String
会话 ID。
type
'phone'
电话会话类型。
timeout
Number
会话接入超时时长,0代表不超时。
calleePhoneNumber
String
被叫号码。
callerPhoneNumber
String
主叫号码。
callerLocation
String
主叫号码归属地。
remark
String
备注。
ivrPath
{key: String, label: String}[]
-
用户的 IVR 按键路径,key 表示对应按键,label 表示对应的按键标签。
protectedCallee
String
在开启号码映射时存在,表示被叫。
protectedCaller
String
在开启号码映射时存在,表示主叫。
serverType
'staffSeat' | 'staffPhoneSeat' | 'staffExtensionSeat'
表示呼入到座席哪一端。
staffSeat 为默认值,表示 Web 座席;
StaffPhoneSeat 表示呼入到座席手机;
MiniProgramSeat 表示小程序座席;
staffExtensionSeat 表示呼入到座席绑定的话机。

在线会话呼入

callback 参数
类型
必填
备注
options
sessionId
String
会话 ID。
type
'phone'
电话会话类型。
timeout
Number
会话接入超时时长,0代表不超时。
nickname
String
用户昵称。
avatar
String
用户头像。
remark
String
备注。
peerSource
String
渠道来源。
channelName
String
自定义参数。
clientData
String
用户自定义参数。

音频会话呼入

callback 参数
类型
必填
备注
options
sessionId
String
会话 ID。
type
'voip'
音频会话类型。
timeout
Number
会话接入超时时长,0代表不超时。
callee
String
渠道入口。
calleeRemark
String
渠道入口备注。
userId
String
用户的 openId。
nickname
String
用户授权后可获得微信昵称。
avatar
String
用户授权后可获得微信头像。
remark
String
备注。
peerSource
String
主叫号码归属地。
ivrPath
{key: String, label: String}[]
用户的 IVR 按键路径,key 表示对应按键,label 表示对应的按键标签。
clientData
String
用户自定义参数。

视频会话呼入

callback 参数
类型
必填
备注
options
sessionId
String
会话 ID。
type
'video'
视频会话类型。
timeout
String
会话接入超时时长,0代表不超时。
userId
String
用户的 openId。
nickname
String
用户授权后可获得微信昵称。
avatar
String
用户授权后可获得微信头像。
remark
String
备注。

内部会话呼入

callback 参数
类型
必填
备注
options
sessionId
String
会话 ID。
type
'internal'
内部会话类型。
timeout
Number
会话接入超时时长,0代表不超时。
peerUserId
String
主叫座席的账号。

座席接入会话

tccc.events.userAccessed

callback 参数
类型
必填
备注
options
sessionId
String
会话 ID。
tabUUID
String
开启多 Tab 集成时存在,表示哪个 Tab 接听的会话。

会话超时转接事件

tccc.events.autoTransfer

callback 参数
类型
必填
备注
options
sessionId
String
会话 ID。

会话结束事件

tccc.events.sessionEnded

callback 参数
类型
必填
备注
options
sessionId
String
会话 ID。
closeBy
String
表示挂断方:
user:用户挂断。
seat:座席挂断。
admin:系统挂断。
timer:定时器挂断。
mainReason
String
仅在电话类型,并且挂断方为"admin"时存在,表示挂断原因。
subReason
String
仅在电话类型,并且挂断方为"admin"时存在,表示挂断的详细原因。

外呼成功事件

tccc.events.callOuted

callback 参数
类型
必填
备注
options
sessionId
String
会话 ID。
callerPhoneNumber
String
外呼使用的主叫号码。
calleePhoneNumber
String
被叫号码。
serverType
'staffSeat' | 'staffPhoneSeat' | 'staffExtensionSeat' |
'MiniProgramSeat'
表示座席外呼类型:
staffSeat 为默认值,表示 Web 座席。
StaffPhoneSeat 表示使用手机外呼。
MiniProgramSeat 表示使用小程序外呼。
staffExtensionSeat 表示使用话机外呼。
tabUUID
String
开启多 Tab 集成时存在,表示哪个 Tab 发起的外呼。

外呼对方接听事件

tccc.events.calloutAccepted

callback 参数
类型
必填
备注
options
sessionId
String
会话 ID。

会话转接事件

tccc.events.transfer

callback 参数
类型
必填
备注
options
sessionId
String
会话 ID。

座席状态变更事件

tccc.events.statusChanged

callback 参数
类型
必填
备注

options
status
详细说明请参见 座席状态


座席被踢下线事件

tccc.events.kickedOut

座席多端登录时触发。

座席被强制下线事件

tccc.events.forcedOffline

管理端在管理后台操作座席强制下线后触发。

座席许可不足

tccc.events.licenseInsufficient

SharedWorker 异常

tccc.events.workerUnhealthy

多 Tab 场景下,底层的 SharedWorker 遇到了无法自愈的异常,建议用户重启浏览器尝试恢复。

语音识别事件

tccc.events.asr

callback 参数
类型
必填
备注
options
sessionId
String
会话 ID。
result
Object
语音识别结果。
flow
'IN' | 'OUT'
识别方向
IN:“我”收到的语音,三方通话 场景下,其他座席的语音也会被标记为 IN,业务侧可根据 userId 做进一步区分。
OUT:“我”发出去的语音。

userId
String
当前语音识别结果对应的 userId。
ASR 识别结果结构体
字段名
类型
描述
slice_type
Integer
识别结果类型:
0:一段话开始识别。
1:一段话识别中,voice_text_str 为非稳态结果(该段识别结果还可能变化)。
2:一段话识别结束,voice_text_str 为稳态结果(该段识别结果不再变化)。
根据发送的音频情况,识别过程中可能返回的 slice_type 序列有:
0-1-2:一段话开始识别、识别中(可能有多次1返回)、识别结束。
0-2:一段话开始识别、识别结束。
2:直接返回一段话完整的识别结果。
index
Integer
当前一段话结果在整个音频流中的序号,从0开始逐句递增。
示例值:0
start_time
Integer
当前一段话结果在整个音频流中的起始时间。
示例值:60
end_time
Integer
当前一段话结果在整个音频流中的结束时间。
示例值:2700
voice_text_str
String
当前一段话文本结果,编码为 UTF8。
示例值:ASR 语音识别结果。
word_size
Integer
当前一段话的词结果个数。
示例值:1
word_list
Word Array
当前一段话的词列表,Word 结构体格式为:
word:String 类型,该词的内容。
start_time:Integer 类型,该词在整个音频流中的起始时间。
end_time:Integer 类型,该词在整个音频流中的结束时间。
stable_flag:Integer 类型,该词的稳态结果,0表示该词在后续识别中可能发生变化,1表示该词在后续识别过程中不会变化。
示例值: [{"word":"我","start_time":380,"end_time":680,"stable_flag":1}]

令牌(登录)已过期

tccc.events.tokenExpired

收到此事件,业务侧可提醒用户通过刷新页面的方式重新获取 token 登录。
callback 参数
类型
必填
备注
options
code
String
错误码。
message
String
错误信息。
code
message
"-4013"
账号欠费,请到腾讯云控制台查看。
"-2040"
操作失败,在线会话许可不足,请联系管理员。
"-2039"
操作失败,语音通话许可不足,请联系管理员。
"-2037"
操作失败,无工作台登录权限。
"-2034"
操作失败,当前可用座席许可数量不足,请立即联系管理员或登录控制台购买更多座席许可。
"-2020"
登录失败,同时在线的座席数不能超过购买的有效座席数,请联系管理员。
"-2017"
您已被管理员强制下线,如需登录请联系管理员恢复上线。
"-2015"
登录票据过期,请重新登录。
"ECONNABORTED"
HTTP 请求超时,请重试。
"-1"
websocket connect 超时,请重试。
"-100"
初始化 SharedWorker 失败。

初始化参数

TCC Web SDK 允许在初始化时,新增 dataset 参数用于开启功能特性,使用方法如下:
function injectTcccWebSDK(SdkURL) {
if (window.tccc) {
console.warn('已经初始化SDK了,请确认是否重复执行初始化');
return;
}
return new Promise((resolve, reject) => {
const script = document.createElement('script');
script.setAttribute('crossorigin', 'anonymous');
script.src = SdkURL;
/*
* 增加dataset参数,表示开启/关闭功能特性
*/
script.dataset.xxx = 'true'
document.body.appendChild(script);
})
}
相关 dataset 如下表:
dataset 参数
备注
enableShared
表示启用 多 Tab 功能
disableNotification
关闭浏览器通知。
disableRingtone
关闭 SDK 所有铃声。
disableCDR
关闭 SDK 工作台服务记录展示。
disableUI
不初始化 SDK 所有 UI,包括工作台和通话条。
disablePreloadMic
登录后不启动麦克风,并且每次通话完成后释放麦克风。
enableOfflineSync
默认值为 false。设置为 true,在多 Tab 场景下,用户在一个 Tab 页 offline,其余 Tab 页状态会同步 offline。
enableOfflineOnLastTabExit
默认值为 false。设置为 true,在多 Tab 场景下,用户关闭或者刷新最后一个 Tab 页时自动 offline(offline 后再次 online, SDK 会使用管理端配置的默认状态)。

多 Tab 集成 SDK

默认情况下,TCCC Web SDK 只允许在一个地方登录,多处登录会触发 kickedOut 事件。开启多 Tab 功能后,任意一个页面发起的通话,都会在其他页面显示,开发者可根据业务逻辑自行隐藏 UI,或者监听对应事件处理。

限制条件

同一个浏览器的多个窗口,注意不能开启无痕模式。
SDK 集成在业务系统处于同一个域名下。
不支持移动端浏览器。

集成步骤

1. 初始化 SDK,参考 Web
2. 增加 enableShared 参数,表示启用多 Tab 功能。
function injectTcccWebSDK(SdkURL) {
if (window.tccc) {
console.warn('已经初始化SDK了,请确认是否重复执行初始化');
return;
}
return new Promise((resolve, reject) => {
const script = document.createElement('script');
script.setAttribute('crossorigin', 'anonymous');
script.src = SdkURL;
/*
* 增加enableShared,表示启用多Tab功能
*/
script.dataset.enableShared = 'true'
document.body.appendChild(script);
script.addEventListener('load', () => {
window.tccc.on(window.tccc.events.ready, ({ tabUUID }) => {
resolve('初始化成功,当前tabUUID为' + tabUUID)
});
window.tccc.on(window.tccc.events.tokenExpired, ({message}) => {
console.error('初始化失败', message)
reject(message)
})
})
})
}
3. 处理多 Tab 逻辑。
触发 callOuted (外呼成功)和 userAccessed (座席接听成功)事件时,会增加 tabUUID 字段,表示哪个页面发起的外呼/接听。
let curTabUUID = '';

window.tccc.on(window.tccc.events.ready, ({ tabUUID }) => {
console.log('初始化成功,当前tabUUID为' + tabUUID)
curTabUUID = tabUUID;
});

window.tccc.on(window.tccc.events.callOuted, ({ sessionId, tabUUID }) => {
if (tabUUID && tabUUID !== curTabUUID) {
// 接收到其他页面的外呼成功事件,业务可自行处理
}
})

window.tccc.on(window.tccc.events.userAccessed, ({ sessionId, tabUUID }) => {
if (tabUUID && tabUUID !== curTabUUID) {
// 接收到其他页面的接听成功事件,业务可自行处理
// 此处为示例代码,会忽略该事件
return;
}
})