SDK API 文档

最近更新时间:2026-04-13 14:28:02

我的收藏
注意:
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
});
});