本文介绍如何安装并使用扣子 Chat SDK,开发者可以参考本文档在自己开发的网站或 App 中快速实现智能对话功能。适用于智能客服、答疑助手或企业内部的 IT 支持机器人等场景。
Chat SDK 的运行环境要求如下表所示。
|
浏览器 |
版本限制 |
|---|---|
|
Chrome |
87.0 及以上 |
|
Edge |
88.0 及以上 |
|
Safari |
14.0 及以上 |
|
Firefox |
78.0 及以上 |
访问密钥用于 Chat SDK 的身份认证与鉴权。根据使用场景选择合适的鉴权方式,各鉴权方式的区别请参见鉴权方式概述。
|
场景 |
推荐方案 |
说明 |
参考文档 |
|---|---|---|---|
|
开发调试 |
个人访问令牌(PAT) |
快速跑通 Chat SDK 的整体流程。 |
|
|
生产环境 |
服务访问令牌(SAT) |
操作更简单,能够有效简化授权流程,适合需要长期稳定访问且无需进行会话隔离的场景。 |
|
|
OAuth 鉴权 |
支持渠道用户访问智能体、会话隔离(即智能体不同账号的消息内容互相隔离)。 |
访问密钥需被授予以下权限,才能正常使用 Chat SDK 的各项能力。Chat SDK 所需的权限列表如下:
|
密钥类型 |
PAT / SAT /普通 OAuth |
渠道 OAuth 访问密钥 |
|---|---|---|
|
权限点 |
|
|
说明
渠道 OAuth 访问密钥的权限点是渠道类型的 OAuth 应用中设置的权限点,创建应用并授权的详细说明可参考OAuth JWT 授权(渠道场景)。
你可以通过 Playground 调试与体验 Chat SDK 各配置项的功能和效果。
在智能体或 AI 应用的发布页面,选择 Chat SDK,并单击发布。发布的详细流程可参考:
进入发布页面复制 SDK 安装代码。
将步骤二中复制的安装代码粘贴到网页中,例如
标签内,通过script 标签加载 Chat SDK 的 js 代码。<html lang="en">
<head>
<meta charset="utf-8">
<link rel="stylesheet" href="./main.css" />
</head>
<body>
<!-- Install SDK -->
<script src="https://lf-cdn.coze.cn/obj/unpkg/flow-platform/chat-app-sdk/1.2.0-beta.20/libs/cn/index.js"></script>
<script src="./index.js"></script>
</body>
</html>
<script type="text/javascript">
var webSdkScript = document.createElement('script');
webSdkScript.src = 'https://lf-cdn.coze.cn/obj/unpkg/flow-platform/chat-app-sdk/1.2.0-beta.20/libs/cn/index.js';
document.head.appendChild(webSdkScript);
webSdkScript.onload = function () {
new CozeWebSDK.WebChatClient({
"config": {
"type": "app",
"appInfo": {
"appId": "744467616885227****",
"workflowId": "744633266780782****"
}
},
"auth": {
"type": "token",
"token": "pat_********",
onRefreshToken: function () {
return "pat_********"
}
}
});
}
</script>
说明
示例代码中的版本号 1.2.0-beta.20 为示例,请以 Chat SDK 最新的版本号为准,版本信息请参见Chat SDK 发布历史。
通过调用 CozeWebSDK.WebChatClient 初始化客户端。当前页面中聊天框包括 PC 和移动端两种布局样式,在 PC 端中,聊天框位于页面右下角,移动端聊天框会铺满全屏。
调用 CozeWebSDK.WebChatClient 时,你需要配置 config(智能体信息)和 auth(鉴权信息)。
config:必选参数,表示智能体的配置信息。
调用智能体时,需要设置以下参数:
|
参数 |
是否必选 |
数据类型 |
描述 |
|---|---|---|---|
|
type |
必选 |
String |
Chat SDK 调用的对象。 在调用智能体时,该参数保持默认值 bot。
|
|
bot_id |
必选 |
String |
智能体的 ID。在智能体编排页面的 URL 中,查看 bot 关键词之后的字符串就是智能体 ID。例如 |
|
isIframe |
可选 |
Boolean |
是否使用 iframe方式来打开聊天框,默认为 false。
|
|
botInfo.parameters |
可选 |
Map[String, Any] |
给智能体中的自定义参数赋值并传给对话流。 说明 仅单 Agent(对话流模式)的智能体支持该配置。 |
auth:表示鉴权方式。当未配置此参数时表示不鉴权。为了账号安全,建议配置鉴权。
|
参数 |
数据类型 |
是否必选 |
描述 |
|---|---|---|---|
|
type |
String |
必选 |
可指定为 |
|
token |
String |
type为 token 时必填 |
|
|
onRefreshToken |
Function |
type为 token 时必填 |
在对话过程中,当检测到访问密钥(token)失效时,将自动使用设置的新密钥。 |
初始化示例如下:
const cozeWebSDK = new CozeWebSDK.WebChatClient({
config: {
// 智能体 ID
bot_id: '740849137970326****',
isIframe: false,
// 给自定义参数赋值并传给对话流
botInfo: {
parameters: {
user_name: 'John'
}
}
},
auth: {
// Authentication methods, the default type is 'unauth', which means no authentication is required; it is recommended to set it to 'token', indicating authentication through PAT (Personal Access Token) or OAuth
type: 'token',
// When the type is set to 'token', it is necessary to configure a PAT (Personal Access Token) or OAuth access token for authentication.
token: 'pat_zxzSAzxawer234zASNElEglZxcmWJ5ouCcq12gsAAsqJGALlq7hcOqMcPFV3wEVDiqjrg****',
// When the access token expires, use a new token and set it as needed.
onRefreshToken: () => 'pat_zxzSAzxawersAAsqJGALlq7hcOqMcPFV3wEVDiqjrg****',
}
});
说明
如果要实现不同业务侧用户的会话隔离,即每个用户只能看到自己和智能体的对话历史,你需要将鉴权方式配置为 OAuth JWT 鉴权,通过 session_name 参数实现会话隔离,具体请参见如何实现会话隔离。
调用 CozeWebSDK.WebChatClient 时,你需要配置扣子应用的基础信息以及鉴权参数:
config:必选参数,表示应用的配置信息。
|
参数 |
是否必选 |
数据类型 |
描述 |
|---|---|---|---|
|
type |
必选 |
String |
Chat SDK 调用的对象。 集成扣子应用时,应设置为 app,表示通过 Chat SDK 调用扣子应用。 |
|
isIframe |
非必选 |
Boolean |
是否使用 iframe方式来打开聊天框,默认为
|
|
appInfo |
必选 |
Object |
扣子应用的详细信息。 说明 确保该应用已经发布为 Chat SDK。 |
|
appInfo.appId |
必选 |
String |
AI 应用的 ID。 在扣子应用中打开工作流或对话流,URL 中 project-ide 参数之后的字符串就是 appId。 |
|
appInfo.workflowId |
必选 |
String |
工作流或对话流的 ID。 在扣子应用中打开工作流或对话流,URL 中 workflow 参数之后的字符串就是 workflowId。 |
|
appInfo.parameters |
可选 |
Map[String, Any] |
给应用中的自定义参数赋值并传给对话流。 |
auth:表示鉴权方式。当未配置此参数时表示不鉴权。为了账号安全,建议配置鉴权。
|
参数 |
数据类型 |
是否必选 |
描述 |
|---|---|---|---|
|
type |
String |
必选 |
可指定为 |
|
token |
String |
type为 token 时必填 |
|
|
onRefreshToken |
Function |
type为 token 时必填 |
在对话过程中,当检测到访问密钥(token)失效时,将自动使用设置的新密钥。 |
示例如下:
const cozeWebSDK = new CozeWebSDK.WebChatClient({
config: {
type: 'app', // 应用类型
isIframe: false, // 是否在iframe中运行
appInfo: { // 应用配置信息
appId: '744189632066042****',
workflowId: '744229754050396****',
parameters: { // 给自定义参数赋值并传给对话流
user_name: 'John'
}
}
},
auth: {
// Authentication methods, the default type is 'unauth', which means no authentication is required; it is recommended to set it to 'token', indicating authentication through PAT (Personal Access Token) or OAuth
type: 'token',
// When the type is set to 'token', it is necessary to configure a PAT (Personal Access Token) or OAuth access token for authentication.
token: 'pat_zxzSAzxawer234zASNElEglZxcmWJ5ouCcq12gsAAsqJGALlq7hcOqMcPFV3wEVDiqjrg****',
// When the access token expires, use a new token and set it as needed.
onRefreshToken: () => 'pat_zxzSAzxawer234zASNElEglZxcmWJ5ouCcq12gsAAsqJGALlq7hcOqMcPFV3wEVDiqjrg****',
}
});
开发者可以按需调整对话框的多种展示效果,例如展示的用户信息、对话框 UI 效果、悬浮球展示、底部文案等。
你可以在 WebChatClient 方法中添加各种属性,实现对应的效果。目前支持的属性如下:
|
功能 |
属性 |
说明 |
|---|---|---|
|
userInfo |
用于设置对话框中的显示用户信息,包括对话框中的用户头像、用户昵称、用户的业务 ID。 |
|
|
ui.base |
用于配置聊天窗口的整体 UI 效果,包括应用图标、页面展示模式(移动端或 PC 端)、系统语言属性、聊天框页面层级。 |
|
|
ui.asstBtn |
控制是否在页面右下角展示悬浮球。默认展示,用户点击悬浮球后将弹出聊天窗口。 |
|
|
ui.footer |
隐藏底部文案或改为其他文案,支持在文案中设置超链接。 |
|
|
ui.header |
用于控制是否展示顶部的标题栏和关闭按钮,默认展示。 |
|
|
ui.chatBot |
用于控制聊天框的 UI 和基础能力,包括:
|
|
|
ui.chatBot |
配置是否允许用户对智能体的回答进行评价(点赞 / 点踩)。 |
|
|
ui.conversations |
配置是否启用会话列表功能。 |
若需在页面卸载或特定场景下关闭 Chat SDK,可调用 destroy 方法销毁客户端,释放资源。
<script>
const client = new CozeWebSDK.WebChatClient(options);
client.destroy();
</script>
你可以配置对话框中的用户信息、布局、悬浮球、底部文案、顶部标题栏等 UI 元素,以满足品牌风格需求。
userInfo 参数用于设置对话框中显示的用户信息,包括对话框中的用户头像和用户昵称。同时,此处指定的用户 ID 也会通过发起对话 API 传递给扣子服务端。
|
参数 |
数据类型 |
是否必选 |
示例 |
描述 |
|---|---|---|---|---|
|
userInfo.url |
String |
必选 |
https://example.coze.cn/obj/eden-cn/lm-lgvj/ljhwZthlaukjlkulzlp/coze/coze-logo.png |
用户头像的 URL 地址,需为一个可公开访问的地址。 |
|
userInfo.nickname |
String |
必选 |
John |
用户的昵称。 |
|
userInfo.id |
String |
可选 |
user123 |
用户的 ID,也就是用户在你的网站或应用中的账号 ID( |
配置示例如下:
const cozeWebSDK = new CozeWebSDK.WebChatClient({
config: {
botId: '740849137970326****',
isIframe: false,
},
auth: {
type: 'token',
token: 'pat_zxzSAzxawer234zASNElEglZxcmWJ5ouCcq12gsAAsqJGALlq7hcOqMcPFV3wEVDiqjrg****',
onRefreshToken: async () => 'pat_zxzSAzxawer234zASNElEglZxcmWJ5ouCcq1Diqjrg****',
},
// 配置用户信息
userInfo: {
id: '12345',
url: 'https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/obric/coze/favicon.1970.png',
nickname: 'John',
},
});
ui.base 参数用于添加聊天窗口的整体 UI 效果,包括应用图标、页面布局、语言属性等。
|
参数 |
数据类型 |
是否必选 |
示例 |
描述 |
|---|---|---|---|---|
|
icon |
String |
可选 |
https://example.com/obj/coze-web-cn/obric/coze/favicon.1970.png |
应用图标,必须是一个可访问的公开 URL 地址。如果不设置,则使用默认扣子图标。 说明 扣子企业旗舰版支持将 icon 修改为自定义的品牌 Logo,扣子团队版和个人版不支持自定义品牌。 |
|
layout |
String |
可选 |
pc |
聊天框窗口的布局风格,支持设置为:
未设置此参数时,系统会自动识别设备,设置相应的布局风格。 |
|
lang |
String |
可选 |
zh-CN |
系统语言,例如工具提示信息的语言。
|
|
zIndex |
Number |
可选 |
1000 |
用于控制聊天框在网页中的页面层级,避免被其他元素遮挡。值越大,显示在越上层。详细信息可参考MDN-zIndex。 |
示例代码如下:
// 在WebChatClient参数中,添加ui.base配置
const cozeWebSDK = new CozeWebSDK.WebChatClient({
config: {
botId: '740849137970326****',
isIframe: false,
},
auth: {
type: 'token',
token: 'pat_zxzSAzxawer234zASNElEGALlq7hcOqMcPFV3wEVDiqjrg****',
onRefreshToken: async () => 'pat_zxzSAzxawer2OqMcPFV3wEVDiqjrg****',
},
// 配置用户信息
userInfo: {
id: 'user123',
url: 'https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/obric/coze/favicon.1970.png',
nickname: '樱桃',
},
// 配置聊天窗口的整体 UI 效果,包括应用图标、页面布局、语言属性等。
ui: {
base: {
icon: 'https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/obric/coze/favicon.1970.png',
layout: 'pc',
zIndex: 1000,
}
},
});
ui.asstBtn 参数用于控制是否在页面右下角展示悬浮球。默认展示,用户点击悬浮球后将弹出聊天窗口。
|
参数 |
数据类型 |
是否必选 |
示例 |
描述 |
|---|---|---|---|---|
|
isNeed |
Boolean |
可选 |
true |
是否在页面右下角展示悬浮球。
|
示例代码如下:
// 在WebChatClient参数中,添加ui.asstBtn配置
const cozeWebSDK = new CozeWebSDK.WebChatClient({
config: {
botId: '740849137970326****',
isIframe: false,
},
auth: {
type: 'token',
token: 'pat_zxzSAzxawer234zASNElEGALlq7hcOqMcPFV3wEVDiqjrg****',
onRefreshToken: async () => 'pat_zxzSAzxawer2OqMcPFV3wEVDiqjrg****',
},
ui: {
// 悬浮球配置
asstBtn: {
isNeed: true // 展示悬浮球
}
}
});
// 在WebChatClient参数中,添加ui.asstBtn配置
const cozeWebSDK = new CozeWebSDK.WebChatClient({
config: {
botId: '740849137970326****',
isIframe: false,
},
auth: {
type: 'token',
token: 'pat_zxzSAzxawer234zASNElEGALlq7hcOqMcPFV3wEVDiqjrg****',
onRefreshToken: async () => 'pat_zxzSAzxawer2OqMcPFV3wEVDiqjrg****',
},
ui: {
// 悬浮球配置
asstBtn: {
isNeed: false // 隐藏悬浮球
}
}
});
隐藏悬浮球时,你可以通过以下方式显示聊天框或隐藏聊天框。
<body>
<button onClick={() => {
cozeWebSDK.showChatBot();
}}>显示聊天框</button>
<button onClick={() => {
cozeWebSDK.hideChatBot();
}}>隐藏聊天框</button>
</body>
Chat SDK 悬浮球的位置默认在页面右下角,不支持移动,如果需要调整悬浮球的位置,你可以隐藏默认的悬浮球,自定义悬浮球的位置和样式,具体请参见Chat SDK 悬浮球位置如何移动?。
聊天框底部会展示对话服务的提供方信息,默认为Powered by coze. AI-generated content for reference only.。开发者通过 ui.footer 参数隐藏此文案或改为其他文案,支持在文案中设置超链接。
底部文案默认展示效果如下:
footer 参数配置说明如下:
|
参数 |
数据类型 |
是否必选 |
示例 |
描述 |
|---|---|---|---|---|
|
isShow |
Boolean |
可选 |
true |
是否展示底部文案模块。
|
|
expressionText |
String |
可选 |
Powered by {{name}} {{name1}} |
底部显示的文案信息。支持添加以下格式的内容:
|
|
linkvars |
Object |
可选 |
{ name: { text: ‘A’, link: ‘https://www.test1.com’ }, name1: { text: ‘B’, link: ‘https://www.test2.com’ } } |
用于定义
替换后示例: |
配置示例如下:
const cozeWebSDK = new CozeWebSDK.WebChatClient({
config: {
botId: '740849137970326****',
isIframe: false,
},
auth: {
type: 'token',
token: 'pat_zxzSAzxawer234zASNElEglZxcmWJ5ouCcq12gsAAsqJGALlq7hcOqMcPFV3wEVDiqjrg****',
onRefreshToken: async () => 'pat_zxzSAzxawer234zASNElEglZxcmWJ5ouCcq12gsAAsqJGALlq7hcOqMcPFV3wEVDiqjrg****',
},
//配置用户信息
userInfo: {
id: '123',
url: 'https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/obric/coze/favicon.1970.png',
nickname: 'John',
},
// 配置聊天窗口的整体 UI 效果,包括应用图标、页面布局、语言属性等。
ui: {
base: {
icon: 'https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/obric/coze/favicon.1970.png',
layout: 'pc',
zIndex: 1000,
},
// 悬浮球配置
asstBtn: {
isNeed: true,
},
//配置底部文案
footer: {
isShow: true,
expressionText: 'Powered by {{name}} {{name1}}',
linkvars: {
name: {
text: 'A',
link: 'https://www.test1.com'
},
name1: {
text: 'B',
link: 'https://www.test2.com'
}
}
}
}
},
});
此配置的对应的展示效果如下:
聊天框顶部默认展示智能体名称、icon 及关闭按钮。展示效果类似如下:
您可以通过 ui.header 参数配置是否展示顶部标题栏和关闭按钮,header 参数配置说明如下:
|
参数 |
数据类型 |
是否必选 |
描述 |
|---|---|---|---|
|
isShow |
Boolean |
可选 |
是否展示顶部标题栏,默认为 true。
|
|
isNeedClose |
String |
可选 |
是否展示顶部的关闭按钮,默认为 true。
|
配置示例如下:
const cozeWebSDK = new CozeWebSDK.WebChatClient({
config: {
botId: '740849137970326****',
isIframe: false,
},
auth: {
type: 'token',
token: 'pat_zxzSAzxawer234zASNElEglZxcmWJ5ouCcq12gsAAsqJGALlq7hcOqMcPFV3wEVDiqjrg****',
onRefreshToken: async () => 'pat_zxzSAzxawer234zASNElEglZxcmWJ5ouCcq12gsAAsqJGA*********',
},
//配置用户信息
userInfo: {
id: '123',
url: 'https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/obric/coze/favicon.1970.png',
nickname: 'John',
},
// 配置聊天窗口的整体 UI 效果,包括应用图标、页面布局、语言属性等。
ui: {
base: {
icon: 'https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/obric/coze/favicon.1970.png',
layout: 'pc',
zIndex: 1000,
},
// 悬浮球配置
asstBtn: {
isNeed: true,
},
//配置顶部标题栏
header: {
isShow: true,
isNeedClose: true,
},
},
});
chatBot 参数用于控制聊天框的 UI 和基础能力,包括标题、大小、位置等基本属性,还可以指定是否支持在聊天框中上传文件。此参数同时提供多个回调方法,用于同步聊天框显示、隐藏等事件通知。
配置说明如下:
|
参数 |
数据类型 |
是否必选 |
示例 |
描述 |
|---|---|---|---|---|
|
title |
String |
可选 |
电商客服 |
聊天框的标题,若未配置,使用默认名称 |
|
uploadable |
Boolean |
可选 |
true |
是否开启聊天框的上传能力。
|
|
width |
Number |
可选 |
500 |
PC 端窗口的宽度,单位为 px,默认为 460。 |
|
el |
Element |
可选 |
见下文的示例代码 |
设置聊天框放置位置的容器(Element)。
|
|
isNeedAudio |
Boolean |
可选 |
true |
设置聊天框中是否允许语音输入。
默认值:
|
|
isNeedFunctionCallMessage |
Boolean |
可选 |
true |
设置是否在聊天框中显示插件工具调用的信息。
|
|
isNeedAddNewConversation |
Boolean |
可选 |
true |
设置是否在聊天框中显示创建新会话功能。
|
|
isNeedQuote |
Boolean |
可选 |
true |
设置是否支持对智能体或应用回复的消息进行追问。
说明 仅支持对返回的文本和图片消息进行追问,不支持对卡片和文件进行追问。 |
相关回调:
在以下示例中,聊天框标题为 Kids’ Playmate | Snowy,并开启上传文件功能。
对应的代码示例如下:
const cozeWebSDK = new CozeWebSDK.WebChatClient({
config: {
botId: '740849137970326****',
isIframe: false,
},
auth: {
type: 'token',
token: 'pat_zxzSAzxawer234zASNElEglZxcmWJ5ouCcq12gsAAsqJGALlq7hcOqMcPFV3wEVDiqjrg****',
onRefreshToken: async () => 'pat_zxzSAzxawer234zASNElEglZxcmWJ5ouCcq12gsAAsqJGALlq7hcOqMcPFV3wEVDiqjrg****',
},
userInfo: {
id: '123',
url: 'https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/obric/coze/favicon.1970.png',
nickname: 'John',
},
ui: {
base: {
icon: 'https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/obric/coze/favicon.1970.png',
layout: 'pc',
zIndex: 1000,
},
asstBtn: {
isNeed: true,
},
footer: {
isShow: true,
expressionText: 'Powered by {{name}} {{name1}}', linkvars: {
name: {
text: 'A',
link: 'https://www.test1.com'
},
name1: {
text: 'B',
link: 'https://www.test2.com'
}
}
},
//配置聊天框
chatBot: {
title: "Kids' Playmate | Snowy",
uploadable: true,
width: 800,
el: undefined,
isNeedAddNewConversation: true,
isNeedQuote: true,
onHide: () => {
// todo...
},
onShow: () => {
// todo...
},
},
},
});
通过 chatbot 的 el 参数设置组件的示例代码如下:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<!-- Do not delete start -->
<link rel="stylesheet" href="./main.css" />
<!-- Do not delete end -->
</head>
<body>
<button onclick="onClick()">Show</button>
<div id="id1" style="position: absolute; top: 100px; left: 100px;width: 200px; height: 500px"></div>
<script src=" https://lf-cdn.coze.cn/obj/unpkg/flow-platform/chat-app-sdk/0.1.0-alpha.xd411cb3b3d/libs/cn/index.js"></script>
<!-- Do not delete start -->
<script src="./index.js"></script>
</body>
</html>
const chatBot = new CozeWebSDK.WebChatClient({
config: {
bot_id: '740849137970326****',
},
auth: {
type: 'token',
token: 'pat_zxzSASNElEglZxcmWJ5ouCcqeMtogsA1sqJGA4lq7hceqMc5FV3wEVDiqjrg****',
onRefreshToken: async () => 'pat_zxzSASNElEglZxcmWJ5ouCcqeMtogsA1sqJGA4lq7hceqMc5FV3wEVDiqjrg****',
},
ui: {
asstBtn: {
isNeed: false,
},
chatBot: {
el: document.getElementById('id1')
}
}
});
function onClick() {
chatBot.showChatBot();
}
你可以在 chatBot 参数中配置是否允许用户对智能体的回答进行评价(点赞 / 点踩),默认禁用评价功能。
|
参数 |
数据类型 |
是否必选 |
描述 |
|---|---|---|---|
|
feedback |
Object |
可选 |
用于配置用户对智能体的回答进行评价(点赞 / 点踩)。 |
|
feedback.isNeedFeedback |
Boolean |
可选 |
聊天界面中是否显示用户反馈(点赞 / 点踩)按钮。
|
|
feedback.feedbackPanel |
Object |
可选 |
配置当用户反馈不满意时,显示的反馈卡片的内容。 |
|
feedback.feedbackPanel.title |
String |
可选 |
反馈卡片顶部的引导文本,用于解释反馈目的,例如: |
|
feedback.feedbackPanel.placeholder |
String |
可选 |
反馈输入框内的占位文本,提示用户输入内容例如: |
|
feedback.feedbackPanel.tags |
Array |
可选 |
预设的反馈标签列表,用户可快速选择问题类型。 |
|
feedback.feedbackPanel.tags.label |
String |
可选 |
标签的文本内容,例如: |
|
feedback.feedbackPanel.tags.isNeedDetail |
Boolean |
可选 |
设置当用户选择此标签后,是否强制要求其填写详细描述。
|
示例代码如下:
ui: {
chatBot: {
feedback: {
isNeedFeedback: true,
feedbackPanel: {
title: '您对这个回答有什么看法?请告诉我们',
placeholder: '请详细描述您的问题...',
tags: [
{
label: '信息不正确'
},
{
label: '涉及敏感信息',
isNeedDetail: true
}
]
}
}
}
}
ui.conversations 参数用于控制是否展示会话列表功能。开启后,聊天框左上角会新增一个会话列表按钮,用户可借此查看历史对话、重新发起对话、创建新的会话、重命名或删除会话,实现便捷的会话管理。
|
参数 |
数据类型 |
是否必选 |
描述 |
|---|---|---|---|
|
isNeed |
boolean |
可选 |
是否展示会话列表功能。
|
示例代码如下:
ui: {
base: {
icon: 'https://lf-coze-web-cdn.coze.cn/obj/eden-cn/lm-lgvj/****/coze/chatsdk-logo.png',
layout: 'pc',
lang: 'en',
zIndex: 1000
},
header: {
isShow: true,
isNeedClose: true
},
conversations: {
isNeed: true
}
}
扣子 Chat SDK 将持续更新迭代,支持丰富的对话能力和展示效果。你可以在 Chat SDK 的 script 标签中指定 Chat SDK 的最新版本号,体验和使用最新的 Chat SDK 对话效果。
在以下代码中,将 ++{{version}} ++部分替换为 Chat SDK 的最新版本号。你可以在Chat SDK 发布历史中查看最新版本号。
<script src="https://lf-cdn.coze.cn/obj/unpkg/flow-platform/chat-app-sdk/{{version}}/libs/cn/index.js"></script>
<script type="text/javascript">
var webSdkScript = document.createElement('script');
webSdkScript.src = 'https://lf-cdn.coze.cn/obj/unpkg/flow-platform/chat-app-sdk/{{version}}/libs/cn/index.js';
document.head.appendChild(webSdkScript);
webSdkScript.onload = function () {
new CozeWebSDK.WebChatClient({
"config": {
"type": "app",
"appInfo": {
"appId": "744467616885227****",
"workflowId": "744633266780782****"
}
},
"auth": {
"type": "token",
"token": "pat_********",
onRefreshToken: function () {
return "pat_********"
}
}
});
}
</script>
如果不再需要通过 Chat SDK 使用 AI 应用,可以在发布页面点击解绑按钮。一旦解绑,智能体或应用就无法通过集成的 Web 应用程序使用。 如果您想恢复 Web 应用程序的访问,需要再次将智能体或应用发布为 Chat SDK。
以下是一段完整的 Chat SDK 调用智能体的代码示例。
<!doctype html>
<html lang="en">
<head>
<style>
/* 修复:CSS 需用 */
#position_demo {
position: absolute;
right: 10px;
bottom: 20px;
}
</style>
</head>
<body>
<h1>Hello World</h1>
<div id="position_demo"></div>
<script src="https://lf-cdn.coze.cn/obj/unpkg/flow-platform/chat-app-sdk/1.2.0-beta.20/libs/cn/index.js"></script>
<script>
const cozeWebSDK = new CozeWebSDK.WebChatClient({
// 智能体或应用基础设置
config: {
type: 'bot', // 类型:集成智能体设为'bot',集成应用需设为'app'
bot_id: '7561768844642***', // 智能体ID
isIframe: false, // 是否使用iframe方式打开聊天框
},
// 鉴权配置:设置鉴权方式、访问密钥及刷新逻辑
auth: {
type: 'token',
token: 'cztei_q0SbqI7WHxRIIjNEaYR0bHafqtUqjRsBlGG****', // 访问密钥
onRefreshToken: async () => 'token' // 密钥过期时返回新密钥
},
// 用户信息配置
userInfo: {
id: 'user123', // 用户ID
url: 'https://lf-coze-web-cdn.coze.cn/obj/eden-cn/lm-lgvj/ljhwZthlaukjlkulzlp/coze/coze-logo.png', // 用户头像URL
nickname: 'John', // 用户昵称
},
// UI配置:控制聊天窗口的整体样式、功能显示及布局
ui: {
// 基础UI配置:应用图标、布局类型、语言及层级
base: {
icon: 'https://lf-coze-web-cdn.coze.cn/obj/eden-cn/lm-lgvj/ljhwZthlaukjlkulzlp/coze/chatsdk-logo.png', // 应用图标URL
layout: 'pc', // 布局类型:'pc'适配电脑端,'mobile'适配移动端
lang: 'en', // 系统语言:'en'英文,'zh-CN'中文
zIndex: 1000 // 聊天框层级
},
// 控制标题栏及关闭按钮显示
header: {
isShow: true, // 是否显示顶部标题栏
isNeedClose: true, // 是否显示关闭按钮
},
// 控制右下角悬浮球显示
asstBtn: {
isNeed: true // 展示悬浮球
},
// 底部文案配置(修复:补充linkvars和footer的闭合括号+逗号)
footer: {
isShow: true, // 是否显示底部版权模块
expressionText: 'Powered by {{name}} {{name1}}', // 底部显示的文本信息
linkvars: {
name: {
text: 'A',
link: 'https://www.test1.com'
},
name1: {
text: 'B',
link: 'https://www.test2.com'
}
} // 修复:补充linkvars的闭合括号
}, // 修复:补充footer的闭合括号
// 会话列表配置:控制会话列表显示
conversations: {
isNeed: true, // 是否需要显示会话列表
},
// 聊天框核心配置
chatBot: {
title: '英语学习伙伴', // 聊天框标题
uploadable: true, // 是否支持文件上传
width: 390, // PC端聊天框宽度(单位:px)
isNeedAudio: true, // 是否支持语音功能
isNeedFunctionCallMessage: true, // 是否显示工具调用消息
isNeedAddNewConversation: true, // 是否支持新建会话
isNeedQuote: true, // 是否支持消息引用
// 消息评价
feedback: {
isNeedFeedback: true, // 是否开启消息评价
feedbackPanel: {
title: '您对这个回答有什么看法?请告诉我们', // 反馈卡片顶部的引导文本,用于解释反馈目的
placeholder: '请详细描述您的问题...', // 反馈输入框提示文字
tags: [ // 反馈标签选项
{
label: '内容不够详细', // 标签文本
isNeedDetail: false, // 是否需要详细说明
},
{
label: '内容错误', // 标签文本
isNeedDetail: false, // 是否需要详细说明
},
{
label: '其他', // 标签文本
isNeedDetail: true, // 是否需要详细说明
},
],
},
},
},
},
});
</script>
</body>
</html>
如果需要将不同业务侧用户的会话互相隔离开来,每个用户只能看到自己和智能体的对话历史,请参见如何实现会话隔离。