说明:
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>
CallResponse 描述如下:
参数 | 类型 | 必填 | 备注 | |
response | sessionId | String | 是 | 会话 ID。 |
| calleeLocation | String | 否 | 被叫号码归属地址。 |
| calleePhoneNumber | String | 是 | 被叫号码。 |
| callerPhoneNumber | String | 是 | 外呼时使用的主叫号码。 |
| serverType | String | 是 | |
| 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>
说明:
该 API 需管理员或质检员角色才能调用。
参数 | 类型 | 必填 | 备注 | |
options | sessionId | String | 是 | |
| 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 | |
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;}})