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

SDK API 文档

最近更新时间:2026-07-01 15:55:33
我的收藏
注意:
TCCC 是加载 SDK 后的全局变量,可直接访问。

通用结构

AgentStatus

座席状态。
字段
描述
free
空闲
busy
忙碌
arrange
话后整理
notReady
示忙
rest
小休

CommonSDKResponse

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

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

发送卡片消息

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

参数
参数名称
类型
必填
备注
options
payload
header
String
是
卡片标题。
desc
String
是
卡片描述。
pic
String
是
卡片封面。
url
String
是
卡片跳转地址。
sessionId
sessionId
String
是
发送消息的会话 ID。
//调用示例:
window.tccc.Chat.sendCardMessage({
sessionId: '9dd2e08b-99d9-4ca6-84eb-0353ad65cb1a',//会话 ID
payload: {
header: "这里是标题",
// 商品描述
desc: "这里是描述",
// 商品图片链接
pic: "https://cloudcache.tencent-cloud.com/qcloud/portal/kit/images/presale.a4955999.jpeg",
// 商品跳转链接
url: "https://www.qcloud.com/"
},
})

发送订单消息

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

参数
参数名称
类型
必填
备注
options
payload
guide
String
否
订单标题。
name
String
否
订单名称。
desc
String
否
订单描述。
pic
String
否
订单图片。
customField
Object
否
订单自定义字段。
sessionId
sessionId
String
是
发送消息的会话 ID。
//调用示例:
window.tccc.Chat.sendOrderMessage({
sessionId: '9dd2e08b-99d9-4ca6-84eb-0353ad65cb1a',//会话 ID
payload: {
guide:"引导标题",
name: "订单名称",
desc: "描述",
pic: "https://cloudcache.tencent-cloud.com/qcloud/portal/kit/images/presale.a4955999.jpeg",
customField: [
{
name: "订单状态:", // 字段名称
value: "已完成", // 字段值
customerValue: "customerValue",
},
{
name: "订单金额:", // 字段名称
value: "1000元", // 字段值
customerValue: "customerValue",
},
] ,
},
})

发送自定义消息

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

参数
参数名称
类型
必填
备注
options
payload
title
String
是
自定义消息的标题。
description
String
是
自定义消息的描述。
iconUrl
String
是
自定义消息的图片标题。
extension
any
否
自定义消息的自定义字段。
sessionId
sessionId
String
是
发送消息的会话 ID。
//调用示例:
window.tccc.Chat.sendCustomMessage({
sessionId: '9dd2e08b-99d9-4ca6-84eb-0353ad65cb1a',//会话 ID
payload: {
title: '这里是标题',// 必传参数 自定义消息的标题
description: '这里是描述',// 必传参数 自定义消息的标题
iconUrl: 'https://cloudcache.tencent-cloud.com/qcloud/portal/kit/images/presale.a4955999.jpeg',// 必传参数 自定义消息的图片标题
extension: {
extenson: 1,
},// 自定义消息的自定义字段
},
})

API 选中会话

参数名称
类型
必填
备注
sessionId
string
是
需要切换的会话 ID。
//调用示例:
window.tccc.UI.selectCurrentSession("cae6d226-013b-4cb6-95d3-faffd321ca7a")

发送文本消息

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

参数
参数名称
类型
必填
备注
options
payload
text
String
是
文本消息的内容。
sessionId
sessionId
String
是
发送消息的会话 ID。
//调用示例:
window.tccc.Chat.sendTextMessage({
sessionId: '9dd2e08b-99d9-4ca6-84eb-0353ad65cb1a',//会话 ID
payload: {
text: "123456",
},
});

发送富文本消息

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

参数
参数名称
类型
必填
备注
options
payload
content
String
是
富文本消息的内容。
sessionId
sessionId
String
是
发送消息的会话 ID。
//调用示例:
window.tccc.Chat.sendRichTextMessage({
sessionId: '9dd2e08b-99d9-4ca6-84eb-0353ad65cb1a',//会话 ID
payload: {
content:
"这是我们的配置信息\\n\\n![](https://im-console-chatbot-1303031839.cos.ap-guangzhou.myqcloud.com/1312281038/2024_07/1721357223805.%E8%8B%B9%E6%9E%9C%22%3Cimg%20src%3D1%20onerror%3D%22alert%28123%29%22%3E.jpg)\\n\\n[点击进入查看](https://www.qq.com)",
},
});

主动发起会话

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

参数
类型
必填
备注
options
channelAgentID
String
是
客服号 ID。
ClientUserID
String
是
IM 用户 ID。
//调用示例:
window.tccc.Chat.startFollowUpConversation({
channelAgentID: '@customer_service_account',//客服号id
ClientUserID: '1',//im用户id
});

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

上线

tccc.Agent.online(): void

下线

tccc.Agent.offline(): void

设置座席状态

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

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

获取座席状态

tccc.Agent.getStatus():AgentStatus

Devices(设备相关接口函数)

检测当前浏览器是否支持

tccc.Devices.isBrowserSupported(): boolean

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

返回麦克风设备列表

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.setWorkbenchItemShowConfig({floatButton:{showUnreadCount:true}}): void

Events(事件)

事件监听

tccc.on(event, callback)

取消事件监听

tccc.off(event, callback)

SDK 初始化完成

tccc.events.ready

当 SDK 初始化完成时触发,此时可安全调用 API。

会话呼入

tccc.events.callIn

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

在线会话呼入

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

座席接入会话

tccc.events.userAccessed

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

会话超时转接事件

tccc.events.autoTransfer

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

会话结束事件

tccc.events.sessionEnded

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

会话转接事件

tccc.events.transfer

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

座席状态变更事件

tccc.events.statusChanged

参数
类型
必填
备注
options
status
否
详细说明请参见 座席状态。

会话变更事件

tccc.events.userChanged

参数
类型
必填
备注
options
sessionId
String
是
指定会话 ID。
callInfo
Object
是
会话信息。

会话标记属性变更事件

IMSessionMarkChange

参数
类型
必填
备注
options
sessionId
String
是
指定会话 ID。
mark
string | undefined
否
标记数据。
starStatus
number | undefined
否
标星数据。
tccc.on('IMSessionMarkChange', (event) => {
console.log(event);
});

座席被踢下线事件

tccc.events.kickedOut

座席多端登录时触发。

座席被强制下线事件

tccc.events.forcedOffline

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

会话列表更新

conversationListUpdated

会话列表信息变更时可监听到此事件。
// 请只使用文档中提到的属性,其余属性未来可能会删减
tccc.on('conversationListUpdated', (event) => {
event.data.map((conversationItem) => {
console.log(conversationItem.sessionId)// 会话 ID
console.log(conversationItem.unreadCount)// 会话未读数
console.log(conversationItem.lastMessage)// 会话最后一条消息,格式见https://web.sdk.qcloud.com/im/doc/v3/zh-cn/Message.html
console.log(conversationItem.type)// 会话类型 C2C(内部会话) GROUP(外部会话)
console.log(conversationItem.userProfile)// 内部会话的用户资料
console.log(conversationItem.groupProfile)// 外部会话会话的群组资料
});
});

收到消息监听

messageReceived

座席收到用户消息时可监听到此事件。
// 请只使用文档中提到的属性,其余属性未来可能会删减
tccc.on('messageReceived', (event) => {
event.data.map((messageItem) => {
console.log(messageItem); // 收到的消息 格式见https://web.sdk.qcloud.com/im/doc/v3/zh-cn/Message.html
console.log(messageItem.sessionId); // 收到的消息的会话 ID
});
});

收到消息撤回监听

onMessageRevoked

座席收到用户消息撤回时可监听到此事件。
// 请只使用文档中提到的属性,其余属性未来可能会删减
tccc.on('onMessageRevoked', (event) => {
event.data.map((messageItem) => {
console.log(messageItem.messageId); // 撤回消息的id
console.log(messageItem.sessionId); // 撤回消息的会话 ID
});
});


收到消息修改监听

onMessageModified

座席收到用户消息被修改时可监听到此事件。
// 请只使用文档中提到的属性,其余属性未来可能会删减
tccc.on('onMessageModified', (event) => {
event.data.map((item) => {
console.log(item.message); // 被修改的消息 格式见https://web.sdk.qcloud.com/im/doc/v3/zh-cn/Message.html
console.log(item.sessionId); // 被修改的消息的会话 ID
});
});

联系我们

如果您在接入过程中有任何疑问,请用微信或企业微信扫码加入智能客服交流群进行咨询。