无 UI 用户端集成

最近更新时间:2026-05-22 10:37:48

我的收藏

适用场景

集成即时通信 IM,自实现智能客服 UI。

前提条件

1. 开通智能客服,详情请参见 快速入门
2. 集成即时通信 IM(含 UI 或无 UI 均可),本文以无 UI 集成 IM JavaScript SDK 示例,其它端请参见具体的开发接入文档。

关键说明

智能客服的私有协议,实质是即时通信 IM 的自定义消息。所以发送智能客服消息,您按照文档正确组装和发送“自定义消息”即可。

智能客服协议

激活会话服务流 - src "7"

用户端发送此协议,激活与智能客服机器人或人工客服的会话。
const AIDeskProtocol_Src7 = {
customerServicePlugin: 0,
src: "7",
};

const message = chat.createCustomMessage({
to: "@customer_service_account", // 默认客服号 ID,可换成您自定义的客服号 ID
conversationType: "C2C", // 单聊
payload: {
data: JSON.stringify(AIDeskProtocol_Src7),
}
});

await chat.sendMessage(message, {
onlineUserOnly: true // 必填。消息不存入漫游,且不会进行离线推送
});

用户端接收满意度评价模板信息 - src "9"

智能客服后台发送此协议到用户端,用户端解析并渲染评价模板。效果如下:

const protocol = JSON.parse(message.payload.data);

// 智能客服协议
if (protocol.customerServicePlugin === 0) {
// 满意度评价模板
if (protocol.src === "9") {
const { menuContent } = protocol;
const {
effectiveHour, // 有效时间
expireTime, // 过期时间
head, // 模板头
menu, // 模板菜单
sessionId, // 会话 id
tail, // 模板尾
} = menuContent;
}
}

用户端发起满意度评价 - src "10"

用户端发送此协议,可对机器人或者人工的服务做出打分评价。效果如下:

const AIDeskProtocol_Src10 = {
customerServicePlugin: 0,
src: '10',
menuSelected: {
id: 104,
content: "非常满意!",
sessionId: "ed1dbc77-9679-42b4-8cc3-772c4feeec21"
}
};

const message = chat.createCustomMessage({
to: '@customer_service_account', // 默认客服号 ID,可换成您自定义的客服号 ID
conversationType: 'C2C', // 单聊
payload: {
data: JSON.stringify(AIDeskProtocol_Src10),
}
});

await chat.sendMessage(message, {
onlineUserOnly: true // 必填。消息不存入漫游,且不会进行离线推送
});

分支 - src "15" || src "29"

智能客服后台发送此协议到用户端,用户端解析并渲染分支模板,一般用于转人工时选择客服分组,或者 AI 追问澄清。效果如下:

const protocol = JSON.parse(message.payload.data);

// 智能客服协议
if (protocol.customerServicePlugin === 0) {
// 分支
if (protocol.src === "15" || (protocol.src === "29" && protocol.subtype !== 'welcome_msg')) {
const {
optionType, // 0 - 分支选项点击后隐藏或者设置为不可点击,避免用户重复选择
content
} = protocol;
const {
header,
items, // 分支内容
tail
} = content;
}

// 当用户点击分支,用户端发送文本信息即可
let message = chat.createTextMessage({
to: '@customer_service_account', // 默认客服号 ID,可换成您自定义的客服号 ID
conversationType: 'C2C', // 单聊
payload: {
text: "qiao-test",
},
});
await chat.sendMessage(message);

机器人欢迎卡片 - src "29"

const protocol = JSON.parse(message.payload.data);

// 智能客服协议
if (protocol.customerServicePlugin === 0) {
// 机器人欢迎卡片
if (protocol.src === "29" && protocol.subtype === 'welcome_msg') {
const {
optionType, // 0 - 分支选项点击后隐藏或者设置为不可点击,避免用户重复选择
content
} = protocol;
const {
header,
items, // 分支内容
tail
} = content;
}

// 当用户点击分支,用户端发送文本信息即可
let message = chat.createTextMessage({
to: '@customer_service_account', // 默认客服号 ID,可换成您自定义的客服号 ID
conversationType: 'C2C', // 单聊
payload: {
text: "qiao-test",
},
});
await chat.sendMessage(message);

多轮分支 - src "32"

智能客服后台发送此协议到用户端,用户端解析并渲染多轮分支模板。效果如下:

const protocol = JSON.parse(message.payload.data);

if (protocol.customerServicePlugin === 0) {
// 智能客服协议
if (protocol.src === "32") {
// 多轮分支
const {
optionType, // 0 - 分支选项点击后隐藏 1 - 分支选项固定,点击后不隐藏,用户可多次选择
taskInfo, // 当 optionType 为 1时出现,用户点击选项时将此信息通过 cloudCustomData 带回给智能客服后台
content
} = protocol;
const {
header,
items, // 分支内容
tail
} = content;
}

// 当用户选择【西瓜】,如果是一次性分支,用户端发送文本信息即可。如果是固定分支,需要将 taskInfo 写入 cloudCustomData
let cloudCustomData = "";
if (optionType === 1) {
cloudCustomData = JSON.stringify({
BranchOptionInfo: { ... taskInfo }
});
}
let message = chat.createTextMessage({
to: '@customer_service_account', // 默认客服号 ID,可换成您自定义的客服号 ID
conversationType: 'C2C', // 单聊
payload: {
text: "西瓜",
},
cloudCustomData,
});
await chat.sendMessage(message);

流程说明

流程说明将描述管理员开通客服号,用户从接入客服号到一次会话结束的过程。

步骤1:开通智能客服并将客服号会话加入用户端会话列表

请您先跟随 管理端配置 开通智能客服,开启客服号单聊的功能(后续用户会与客服号(客服号的 UserID 为@customer_service_account)进行单聊)。


步骤2:用户进入客服号会话触发会话流

在用户端进入客服号会话时,请先通过调用 API 对客服号发送触发会话服务流消息,以此自动触发会话服务流。

步骤3:执行客服号配置的流程

在线客服通过不同的自定义消息来完成各种会话服务流交互操作,每一种自定义消息对应一个事件或一种类型的消息,例如,用户发送自定义消息完成会话流中会话启动、提交客服评价 等交互操作,即时通信 IM 后台下发自定义消息给用户以展示分支消息表单消息等。
IM 后台会根据您配置的智能机器人流程,进行各种类型消息的下发或转接人工客服等操作,直到这一次的会话流程结束。

步骤4:会话流结束

会话流结束时会下发会话结束标志位,标志此次会话流程结束。
不同自定义消息的格式可见下方文档,您可以根据自定义消息的字段进行自主开发。

自定义消息格式

本文介绍的自定义消息的 data 字段为 JSON 结构体经过序列化后的值,不同平台获取自定义消息的 data 字段的方式可见各自平台的文档(Android&iOS&Mac&Windows / Web&小程序&uni-app / Flutter / Unity / React Native) 。
在线客服的自定义消息通过 JSON 结构体的 src 字段的值来区分不同类型的消息。
下方展示了自定义消息字段的说明与示例
字段名
字段类型
字段含义
customerServicePlugin
Number
在线客服自定义消息标志位,0代表此消息为在线客服自定义消息
src
String
在线客服自定义消息类型 例如"15" 代表此消息为在线客服的分支类型消息
content 或 menuContent
Any
在线客服自定义消息的内容,不同类型的消息包含不同类型的内容
示例:
{
"customerServicePlugin": 0,//当此字段为0时,表示此自定义消息为在线客服的自定义消息
"src": "15",// 自定义消息类型,15为分支消息类型
"content": {// 分支消息内容
"header": "请输入您想接入的功能",
"items": [{
"content": "人工",
"desc": ""
}, {
"content": "表单选项分支",
"desc": ""
}, {
"content": "表单输入",
"desc": ""
}, {
"content": "返回",
"desc": ""
}],
"tail": ""
}
}

触发会话服务流消息 (src = 7)

消息说明:

用户进入客服号会话页面后,可发送如下 data 字段的自定义消息,以自动触发会话服务流。
后台在接收到此消息后会下发会话评价设置消息(src = 23),以确定用户端是否可以主动发送客服评价。
因此我们建议在进入会话页面时主动发送此自定义消息。
注意:
发送时需要将参数 onlineUserOnly 设置为 true

消息样式:

此消息为标志位消息,无需在消息列表中渲染。

自定义数据字段结构:

{
"customerServicePlugin": 0,
"src": "7"
}

评价消息(src = 9)

消息说明:

满意度评价一般用于客服与用户会话结束后收集用户的满意度评价信息。
满意度评价的设置与详细说明可见 满意度评价文档
用户评价后, selected 字段为用户选择的选项。
注意:
请确保用户的 selected 字段不为空,否则提交记录无效。

消息样式:



自定义数据字段结构:

{
"customerServicePlugin": 0,
"src": "9",
"menuContent": {
"head": "感谢您使用我们的服务,请对此次服务进行评价!",//评价标题
"tail": "感谢您对此次服务作出评价,祝您生活愉快,再见!",//评价结尾
// 评价结构 content为此档评价的描述
"menu": [
{ "id": "101", "content": "非常不满意" },
{ "id": "102", "content": "不满意" },
{ "id": "103", "content": "一般" },
{ "id": "104", "content": "满意" },
{ "id": "105", "content": "非常满意" },
],
"type": 2,// 1代表星级评价,2代表数字评价
"sessionId": "7a67f6bb-8fac-41e5-8bab-78c0259ae5a9",// 评价消息的标识id
"effectiveHour": 12, // 评价消息有效小时
"expireTime": 1691074320 // 评价消息过期时间
"selected": {id: '105', content: '非常满意'} // 如果已经选择过评价,这里即为选择的结果
},
}

评价选择消息(src = 10)

消息说明:

用户在接收到评价消息后,可发送如下 data 字段的自定义消息,以通知后台用户此次的评价结果。
后台在收到选择消息之后,评价消息(src = 9)的 selected 的字段会填充此次选择的数据。

消息样式:

此消息为标志位消息,无需在消息列表中渲染。

自定义数据字段结构:

{
"customerServicePlugin": 0,
"src": "10",
"menuSelected": {
'id': 'id',// 选择的评价档位id
"content": 'content',// 选择的评价档位描述
"sessionId": 'sessionId'// 评价消息的标识id
}
}

正在输入状态(src = 12)

消息说明:

当座席端客服在输入框输入消息时,会下发如下 data 字段的自定义消息,表示座席端客服处于正在输入状态,收到该消息时可在 UI 界面展示 "对方正在输入"。
注意:
发送时需要将参数 onlineUserOnly 设置为 true。

消息样式:

此消息为标志位消息,无需在消息列表中渲染。

自定义数据字段结构:

{
"customerServicePlugin": 0,
"src": "12"
}

分支消息(src = 15)

消息说明:

分支消息用于对用户不同服务类型需求进行分流。
分支消息的设置与详细说明可见 分支消息文档
用户选择分支后,selected 字段为用户选择的选项。
注意:
分支消息的分支触发为用户端发送文本消息。
分支消息的选择匹配为文本的强等匹配,用户端发送的文本消息中的文本必须与分支的文本相同时才会触发此分支。

消息样式:



自定义数据字段结构:

{
"customerServicePlugin": 0,//当此字段为0时,表示此自定义消息为在线客服的自定义消息
"src": "15",// 自定义消息类型,15为分支消息类型
// 分支消息内容
"content": {
// 分支标题
"header": "请输入您想接入的功能",
"items": [{
"content": "人工",
"desc": ""
}, {
"content": "表单选项分支",
"desc": ""
}, {
"content": "表单输入",
"desc": ""
}, {
"content": "返回",
"desc": ""
}],
"tail": "",
// 如果已经选择过分支,这里即为选择的结果
"selected": {"content": "人工"}
}
}

会话结束标志位(src = 19)

消息说明:

当会话流正常结束时后台会下发如下 data 字段的自定义消息。

消息样式:

如您需要展示会话结束标识,可渲染此消息。

自定义数据字段结构:

{
"customerServicePlugin": 0,
"src": "19"
}

会话因超时结束标志位(src = 20)

消息说明:

当会话流因为超时结束时后台会下发如下 data 字段的自定义消息。

消息样式:

如您需要展示会话超时结束标识,可渲染此消息。

自定义数据字段结构:

{
"customerServicePlugin": 0,
"src": "20"
}

表单收集消息(src = 21)

消息说明:

表单收集消息通过提示语引导用户输入信息,用户输入信息将被存储在设定的变量名中,表单类型支持收集文本和选项。
表单收集消息的设置与详细说明可见 表单收集消息文档
用户填写收集信息后, selected 字段为用户填写的内容。
注意:
表单收集消息的收集触发为用户端发送文本消息。

消息样式:



自定义数据字段结构:

// 选项表单结构
{
"customerServicePlugin": 0,
"src": "21",
"content": {
// 选项标题
"header": "你喜欢吃什么?",
// 收集选项
"items": [{
"content": "苹果",
"desc": ""
}, {
"content": "西瓜",
"desc": ""
}, {
"content": "草莓",
"desc": ""
}],
// 1为选项表单
"type": 1,
// 若填写过,则内容为提交的内容
"selected": {
"content": "苹果"
}
}
}

// 文本表单结构
{
"customerServicePlugin": 0,
"src": "21",
"content": {
// 收集标题
"header": "你喜欢吃什么?",
// 0为文本表单
"type": 0,
// 若填写过,则内容为提交的内容
"selected": {
"content": "桃子"
}
}
}

卡片消息(src = 22)

消息说明:

卡片消息用于展示商品/订单类信息,是集标题、图片与跳转链接为一体的自定义消息。用户端可主动向座席发送此类消息。

消息样式:



自定义数据字段结构:

{
"src": "22",
"content": {
// 商品标题
"header": "这里是标题",
// 商品描述
"desc": "这里是描述",
// 商品图片链接
"pic": "https://cloudcache.tencent-cloud.com/qcloud/portal/kit/images/presale.a4955999.jpeg",
// 商品跳转链接
"url": "https://www.qcloud.com/"
customField: [
{
name: "订单金额:", // 字段名称
value: "1000元", // 字段值
position: "", // 值为top:该内容显示在商品图片上方;不填或其它值:则显示在图片下方。
}
]
},
"customerServicePlugin": 0
}

卡片消息触发任务流:

卡片消息传入触发任务流信息字段时可触发任务流,支持写入会话级变量供后续任务流使用。
{
"src": "22",
"customerServicePlugin": 0,
"content": {
"header": "这里是标题",
"desc": "这里是描述",
"pic": "https://cloudcache.tencent-cloud.com/qcloud/portal/kit/images/presale.a4955999.jpeg",
"url": "https://www.qcloud.com/"
},
// 触发任务流信息(选传),传入时卡片消息将触发对应的任务流
"taskTrigger": {
"taskId": 9527, // 任务流 ID
"taskType": 0, // 任务类型 0:标准任务流,1:智能任务流,不传默认标准任务流
"variables": { // 传入任务流的变量,key-value 格式,值支持 String / Number(整数)
"orderId": "123456",
"amount": 100
}
},
// 会话级变量(选传),写入后在该会话后续任务流中可直接使用相关字段,
"sessionLevelVariables": {
"userName": "张三",
"vipLevel": 3
}
}

会话评价设置消息(src = 23)

消息说明:


当用户发送触发会话流消息(src = 7)时,后台会下发此消息。不同值的 menuSendRuleFlag 代表不同的发送规则,具体可见下方。

消息样式:

此消息为标志位消息,无需在消息列表中渲染。

自定义数据字段结构:

// 值为 1 << 0 代表会话结束自动发送
// 值为 1 << 1 代表座席可主动邀评
{
"customerServicePlugin": 0,
"src": "23",
"content": {
// 评价消息发送规则值
"menuSendRuleFlag": 7
}
}

主动拉取客服评价消息(src = 24)

消息说明:

当用户端进入人工服务且评价消息的发送规则包括用户可发送 时,可发送如下 data 字段的自定义消息,以通知后台下发评价消息。后台收到此消息会下发评价消息(src = 9)。
注意:
发送时需要将参数 onlineUserOnly 设置为 true

消息样式:

此消息为标志位消息,无需在消息列表中渲染。

自定义数据字段结构:

{
"customerServicePlugin": 0,
"src": "24",
}

人工会话状态(src = 26)

消息说明:

当用户发送触发会话流消息(src = 7)时,后台会下发此消息。不同值的 content 代表不同人工会话状态。

消息样式:

此消息为标志位消息,无需在消息列表中渲染。

自定义数据字段结构:

// 值为 inSeat 代表接入了人工座席
// 值为 outSeat 代表没有接入人工座席
// 值为 queuing 代表在排队中
// 值为 WaitingForAgentAnswering 代表正在等待客服接听
{
"customerServicePlugin": 0,
"src":"26",
"content":{
"command":"updateSeatStatus",
"content":"inSeat"
}
}

用户主动结束人工会话(src = 27)

消息说明:

当用户端需要主动结束人工会话时,可发送如下 data 字段的自定义消息。用户主动结束人工会话包含以下3种情况:
1. 用户转人工触发排队时,发送此消息可以结束排队,本次会话结束。
2. 客服接待方式为手动接待时,用户转人工分配客服成功后等待客服确认接待的时候,发送此消息可以结束等待,本次会话结束。
3. 用户转人工且成功接入人工客服时,发送此消息可以结束本次会话。
注意:
发送时需要将参数 onlineUserOnly 设置为 true

消息样式:

此消息为标志位消息,无需在消息列表中渲染。

自定义数据字段结构:

{
"customerServicePlugin": 0,
"src": "27",
}

机器人欢迎卡片(src = 29)

消息说明:

当用户首次触发机器人时,后台会下发 subtype 为 welcome_msg 的欢迎卡片消息。
当设置了引导提问且用户的输入在相似度设置区间中,后台会下发 subtype 为 clarify_msg 的引导提问消息。

消息样式:

欢迎卡片:

引导提问:


自定义数据字段结构:

// subtype为welcome_msg时为欢迎卡片
{
"customerServicePlugin": 0,
"src": "29",
"subtype": "welcome_msg",
"content": {
"title": "猜你想问",
"content": "",
"items": [
{
"content": "智能客服提供哪些功能"
},
{
"content": "如何修改机器人知识库"
},
{
"content": "客服在哪里收发消息"
},
{
"content": "如何设置工作时间"
},
{
"content": "是否支持发送满意度评价"
},
{
"content": "机器人功能可以关闭吗"
},
{
"content": "支持哪些消息渠道"
},
{
"content": "什么情况会进入排队"
}
]
}
}

// subtype为clarify_msg时为引导提问消息
{
"customerServicePlugin": 0,
"src": "29",
"subtype": "clarify_msg",
"content": {
"title": "您可能想问:",
"content": "您可能想问:",
"items": [
{
"content": "客服要怎么服务用户?"
},
{
"content": "支持哪些用户咨询渠道?"
},
{
"content": "智能客服提供哪些功能"
},
{
"content": "怎么实现所有的问题都由客服回复"
},
{
"content": "智能客服是什么"
}
]
}
}

机器人富文本(src=30)

消息说明:

当用户在机器人的回答中设置的回复为富文本时且用户的提问命中问题时,后台会下发 Markdown 格式的富文本消息。

消息样式:



自定义数据字段结构:

{
"customerServicePlugin": 0,
"src": "30",
"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)"
}

流式消息(src = 31)

消息说明:

当用户的问题命中了 文档问答,后台会下发 Markdown 格式的流式消息。
说明:
流式消息在用户端请通过监听消息修改的回调(Android & iOS&Mac & Windows / Web&小程序&uni-app / Flutter / Unity / React Native )监听消息内容的增加。

消息样式:



自定义数据字段结构:

{
"customerServicePlugin": 0,
"src": "31",
// chunks代表流式消息的内容
"chunks": [
"",
"您",
"可以在",
"管理",
"端",
"左侧",
"菜单",
],
// isFinished为0时表示流式消息未输出结束,1代表输出结束
"isFinished": 1,
}

多轮任务分支消息(src = 32)

消息说明:

当用户的问题命中了多轮任务的 分支选项 后,后台会下发多轮任务分支消息。

消息样式:



自定义数据字段结构:

{
"customerServicePlugin": 0,//当此字段为0时,表示此自定义消息为在线客服的自定义消息
"src": "32",
"status":1, // 0表示可选择,1表示不可选择,2表示已选择
"optionType":0, // 0表示快捷选项(点击后选项消失),1表示固定按钮(点击后选项不消失)
"taskInfo": {
"taskID": 9527, // 任务流 ID
"nodeID": "node-9b1257ab-e91a-4317-af44-0f38d6e237e5" // 节点 ID,用于后台流转任务流时回到该节点开始流转
"env": "production"
},
// 分支消息内容
"content": {
// 分支标题
"header": "请输入您想接入的功能",
"items": [{
"content": "人工",
"desc": ""
}, {
"content": "表单选项分支",
"desc": ""
}, {
"content": "表单输入",
"desc": ""
}, {
"content": "返回",
"desc": ""
}],
"tail": "",
}
}

// 当分支为固定按钮时,用户点击后将以下数据结构 json 序列化后放到 cloudCustomData 中。
// 若分支为快捷选项时,不需要带 cloudCustomData 字段
{
"BranchOptionInfo": {
"taskID": 9527, // 任务流 ID,从下发的分支消息中取
"nodeID": "node-9b1257ab-e91a-4317-af44-0f38d6e237e5" //节点 ID,从下发的分支消息中取
"env": "production"
}
}

多轮任务信息收集消息(src = 33)

消息说明:

当用户的问题命中了多轮任务的 信息收集 后,后台会下发多轮任务信息收集消息。

消息样式:



自定义数据字段结构:

{
"customerServicePlugin": 0,//当此字段为0时,表示此自定义消息为在线客服的自定义消息
"src": "33",// 自定义消息类型
// 分支消息内容
"content": {
// 分支标题
"tip": "信息收集节点",
"inputVariables": [{
"type": "string", //字符串类型
"name": "你的名字是?", //选项标题
"formType": 0, //0代表输入,1代表选择
"placeholder": "请输入你的名字", //每一个选项的提示语
"isRequired":1, //1:必填, 0非必填
"variableValue": "${name}", // 如果已经提交过信息,则此字段会有值,否则为空
}, {
"type": "string", //字符串类型
"name": "你的地址是?", //选项标题
"formType": 0, //0代表输入,1代表选择
"placeholder": "请输入你的地址", //每一个选项的提示语
"isRequired":1, //1:必填, 0非必填
"variableValue": "${location}", // 如果已经提交过信息,则此字段会有值,否则为空
}, {
"type": "string",
"name:" "你来咨询的问题是?",
"formType": 1, //0代表输入,1代表选择
"chooseItemList":["退款服务","人工服务","信息咨询服务"], //待选项
"isRequired":1, //1:必填, 0非必填
"variableValue": "${question}"
}]
},
"nodeStatus": 0 //表示表单节点的状态,0表示可编辑,1表示不可编辑(未提交),2表示已提交(也不可编辑)
}

// 提交时按照此格式发送自定义消息
{
"customerServicePlugin": 0,//当此字段为0时,表示此自定义消息为在线客服的自定义消息
"src": "33",// 自定义消息类型
// 分支消息内容
"content": {
"inputVariables": [{
"name": "你的名字是?",
"isRequired":1,
"variableValue": "1",
}, {
"name": "你的地址是?",
"isRequired":1,
"variableValue": "2"
}, {
"name:" "你来咨询的问题是?",
"isRequired":1,
"variableValue": ""//非必填可传入空
}]
},
}