AI 助手
扣子 AI 帮助与支持
你好，我是 扣子 文档问答助手 🎉
你在阅读当前文档的过程中，无论对文档概念的解释，还是文档内容方面的疑问，都可以随时向我提问，我会全力为你解答
推荐问题
如何快速了解这个空间的核心内容？
有哪些近期更新的重点文档？
我应该从哪些文档开始阅读？
文档反馈
OpenClaw
进阶配置
技能
工作流教程
智能音视频
图像处理
客服场景
社交娱乐
发布渠道
团队与企业
通过扣子编程搭建的低代码智能体可以一键发布为 Chat SDK，快速部署到你的自建网站中，作为在线智能客服面向网站的用户提供 AI 答疑服务。本文档介绍通过 Chat SDK 搭建网页版在线客服的详细操作步骤。
场景说明
网站作为企业和组织与用户互动的重要平台，其用户体验和运营效率至关重要。AI 客服作为一种强大的工具，能够显著提升网站的功能性和用户体验。
- 即时响应：AI 客服能够实时回答用户的问题，提供 24/7 的即时帮助。
- 个性化服务：通过分析用户的历史对话数据，AI 客服可以提供个性化的推荐和服务。例如，推荐符合用户兴趣的产品或内容，提供定制化的购物建议等。
扣子编程现已推出 Chat SDK 帮助你搭建网页版在线客服。Chat SDK 是一个 JavaScript 库，集成了扣子编程 OpenAPI 的对话、文件上传等能力，便于开发者高效、便捷、快速地搭建一个网页版聊天应用。集成扣子编程 Chat SDK 之后，用户可通过网页悬浮窗方式与 AI 客服对话。
步骤一：搭建并发布客服智能体
在扣子编程中搭建一个客服智能体，并将其发布为 Chat SDK。
- 搭建一个客服智能体。
这里我们以扣子编程的智能客服助手为例。注意智能客服通常需要上传知识库，作为客服智能体的私有数据来源，帮助智能体学习非公开的专有领域知识。这里我们上传扣子编程文档做为扣子助手
你可以参考教程搭建一个 AI 助手智能体完成搭建，也可以从扣子编程模板库中直接复制一个智能客服模板，例如扣子智能客服。
- 将智能体发布为 Chat SDK。
在编排页面右上角单击发布，并选择 Chat SDK 渠道，并单击发布。
未发布为 Chat SDK 的智能体，使用 Chat SDK 时会报错，提示：智能体已经被解绑。
- 确认审核通过。
你可以在发布历史页面查看每次发布的审核结果，审核通过后才能执行后续操作安装 Chat SDK。
步骤二：安装 Chat SDK
进入发布页面复制 SDK 安装代码。
- 在智能体的编排页面，单击发布，进入发布页面。
- 在发布页面，点击安装。
页面将展示安装代码，安装代码中默认使用最新版本的 Chat SDK 配置。复制此代码，此代码将在后续的配置中使用。
- 安装 SDK。
你可以直接在页面中通过 script 标签的形式加载 Chat SDK 的 js 代码，将步骤二中复制好的安装代码粘贴到网页的 区域中即可。
步骤二中复制好的安装代码示例如下：<script src="https://lf-cdn.coze.cn/obj/unpkg/flow-platform/chat-app-sdk/1.1.0-beta.0/libs/cn/index.js"></script>
步骤三：获取访问令牌
访问令牌用于 Chat SDK 鉴权。
说明
- 如果要实现不同业务侧用户的会话隔离，即每个用户只能看到自己和智能体的对话历史，你需要将鉴权方式配置为 OAuth JWT 鉴权，通过 session_name 参数实现会话隔离，具体请参见如何实现会话隔离。
- 测试场景中可以使用个人访问令牌以快速跑通整体流程，线上应用禁止使用个人访问令牌，应使用 OAuth 方式获取访问令牌，Chat SDK 场景下通常使用 JWT Token，关于 JWT Token 的获取方式可参考OAuth JWT 授权（开发者）。
本文档以个人访问令牌为例进行演示。
在个人访问令牌页面，根据页面提示添加一个新令牌，注意需要添加完整的权限，具体权限清单可参考权限要求。
步骤四：配置聊天界面
安装 Chat SDK 后，您现在可以初始化客户端。在页面中通过调用 CozeWebSDK.WebChatClient 来生成聊天框，当前页面中聊天框包括 PC 和移动端两种布局样式。在 PC 端中，聊天框位于页面右下角，移动端聊天框会铺满全屏。
基础配置
调用 CozeWebSDK.WebChatClient 时，必选参数如下：
|
参数 |
是否必选 |
数据类型 |
描述 |
|
|---|---|---|---|---|
|
config |
type |
必选 |
String |
Chat SDK 调用的对象。 在调用智能体时，该参数保持默认值 bot。 |
|
botId |
必选 |
String |
智能体的 ID。在智能体编排页面的 URL 中，查看 bot 关键词之后的字符串就是智能体 ID。例如 |
|
|
auth |
必选 |
String |
表示鉴权方式。当未配置此参数时表示不鉴权。 |
|
示例如下：
const cozeWebSDK = new CozeWebSDK.WebChatClient({
config: {
// Agent ID
botId: '740849137970326****',
isIframe: false,
},
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****',
}
});
高级配置
扣子编程 Chat SDK 支持多种属性配置，开发者可以按需调整对话框的多种展示效果，例如展示的用户信息、对话框 UI 效果、悬浮球展示、底部文案等。
你可以在 WebChatClient 方法中添加各种属性，实现对应的效果。目前支持的全部属性可参考步骤五：配置属性。本文档以常见的属性配置为例进行演示。
设置小助手图标
ui.base 参数用于添加聊天窗口的整体 UI 效果，包括应用图标参数 icon。icon 为 String 类型的可选参数，必须是一个可访问的公开 URL 地址，用于设置对话页面中的小助手头像。
说明
扣子编程企业版支持将 icon 修改为自定义的品牌 Logo，扣子编程团队版和个人版不支持自定义品牌。
在本示例中，可以设置为扣子小助手的图标。
设置效果
示例代码
ui: {
base: {
icon: 'https://lf26-appstore-sign.oceancloudapi.com/ocean-cloud-tos/FileBizType.BIZ_BOT_ICON/3290203753552072_1728716719140087481_I4Wrvxocdg.png?lk3s=50ccb0c5&x-expires=1744880642&x-signature=zWvoLXLwkUiM2igdBcNvxb0zssU%3D',
layout: 'pc',
zIndex: 1000,
}
},
隐藏顶部标题栏
默认展示顶部标题栏。通过 ui.header 参数可以指定是否展示顶部标题栏（不包括关闭按钮）。设置为 false 即可隐藏标题栏。
设置效果
示例代码
header: {
isShow: false
}
设置聊天框标题、位置容器
chatBot 参数用于控制聊天框的 UI 和基础能力，包括标题、大小、位置等基本属性。
小助手在顶部导航栏的默认名称为 Coze Bot，我们需要通过 chatBot.title 参数将其改为**扣子小助手**。
另外，还可以通过 chatBot.el 设置聊天框放置位置的容器（Element）。
- 开发者应自行设置聊天框高度、宽度，聊天框会占满整个元素空间。
- Chat SDK 会自动控制聊天框的显示隐藏，但是对于宿主的 element 元素不会做控制，开发者按需在 onHide、onShow 回调时机中来控制宿主元素的显示隐藏。
相关回调：
- onHide：当聊天框隐藏的时候，会回调该方法。
- onShow: 当聊天框显示的时候，会回调该方法。
- onBeforeShow: 聊天框显示前调用，如果返回了 false，则不会显示。支持异步函数。
- onBeforeHide: 聊天框隐藏前调用，如果返回了 false，则不会隐藏。支持异步函数。
设置效果
示例代码
chatBot: {
title: '扣子小助手',
uploadable: true,
width: 390,
el: undefined,
onHide: () => {
// todo...
},
onShow: () => {
// todo...
},
},
},
},
设置底部文案
底部文案指小助手聊天框底部一行版权文案，展示对话服务的提供方信息，默认为Powered by coze. AI-generated content for reference only.。你可以通过 footer 参数隐藏此文案或改为其他文案，支持在文案中设置超链接。
我们可以将其设置为中文文案 由扣子提供。内容均由 AI 生成，仅供参考。
设置效果
示例代码
footer: {
isShow: true,
expressionText: '由{{name}}提供。内容均由 AI 生成，仅供参考',
linkvars: {
name: {
text: '扣子',
link: 'https://www.coze.cn/'
}
}
}
}
},
可视化调试
了解基础的参数设置之后，你可以通过扣子编程 Playground 可视化调试你的网页客服小助手。
进入扣子编程 Chat SDK Playground，在 index.js 文件中添加步骤四中编写好的配置，并单击运行。
页面右下角会展示扣子编程图标，单击图标即可与你的客服小助手实时对话，查看聊天界面的各项配置是否生效。调试完毕后，将 js 代码添加到网站的前端页面上，就完成了小助手的前端部署。
示例代码
以本文档中调试的扣子小助手为例，完整的 html 示例代码如下：
<!doctype html>
<html lang="en">
<head>
<style>
/* 自定义悬浮入口的位置 */
#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.1.0-beta.0/libs/cn/index.js"></script>
<script>
new CozeWebSDK.WebChatClient({
/**
* Agent or app settings
* for agent
* @param config.bot_id - Agent ID.
* for app
* @param config.type - To integrate a Coze app, you must set the value to app.
* @param config.appInfo.appId - AI app ID.
* @param config.appInfo.workflowId - Workflow or chatflow ID.
*/
config: {
bot_id: '7493834003054297088',
},
/**
* The auth property is used to configure the authentication method.
* @param type - Authentication method, default type is 'unauth', which means no authentication is required; it is recommended to set it to 'token', which means authentication is done through PAT (Personal Access Token) or OAuth.
* @param token - When the type is set to 'token', you need to configure the PAT (Personal Access Token) or OAuth access key.
* @param onRefreshToken - When the access key expires, a new key can be set as needed.
*/
auth: {
type: 'token',
token: 'pat_RFT35rMlSTdzMUcv9ZzhCyfI2Ge0R8XR1zKLuZYuoYy96ysgBSBmnnk5tq4VnbDx',
onRefreshToken: async () => '',
},
/**
* The userInfo parameter is used to set the display of agent user information in the chat box.
* @param userInfo.id - ID of the agent user.
* @param userInfo.url - URL address of the user's avatar.
* @param userInfo.nickname - Nickname of the agent user.
*/
userInfo: {
id: 'user',
url: 'https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/obric/coze/favicon.1970.png',
nickname: 'UserA',
},
ui: {
/**
* The ui.base parameter is used to add the overall UI effect of the chat window.
* @param base.icon - Application icon URL.
* @param base.layout - Layout style of the agent chat box window, which can be set as 'pc' or'mobile'.
* @param base.lang - System language of the agent, which can be set as 'en' or 'zh-CN'.
* @param base.zIndex - The z-index of the chat box.
*/
base: {
icon: 'https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/obric/coze/favicon.1970.png',
layout: 'pc',
lang: 'en',
zIndex: 1000,
},
/**
* Control the UI and basic capabilities of the chat box.
* @param chatBot.title - The title of the chatbox
* @param chatBot.uploadable - Whether file uploading is supported.
* @param chatBot.width - The width of the agent window on PC is measured in px, default is 460.
* @param chatBot.el - Container for setting the placement of the chat box (Element).
*/
chatBot: {
title: '扣子小助手',
uploadable: true,
width: 390
},
/**
* Controls whether to display the floating ball at the bottom right corner of the page.
*/
asstBtn: {
isNeed: true,
},
/**
* The ui.footer parameter is used to add the footer of the chat window.
* @param footer.isShow - Whether to display the bottom copy module.
* @param footer.expressionText - The text information displayed at the bottom.
* @param footer.linkvars - The link copy and link address in the footer.
*/
footer: {
isShow: true,
expressionText: '由{{name}}提供。内容均由 AI 生成，仅供参考',
linkvars: {
name: {
text: '扣子',
link: 'https://www.coze.cn/'
}
}
}
},
});
</script>
</body>
</html>