715 lines
26 KiB
Plaintext
715 lines
26 KiB
Plaintext
配置流程
|
||
步骤一：发布智能体或 AI 应用
|
||
在智能体或 AI 应用的发布页面，选择 Chat SDK，并单击发布。发布的详细流程可参考：
|
||
发布应用为 Chat SDK
|
||
发布智能体到 Chat SDK
|
||
步骤二：获取安装代码
|
||
进入发布页面复制 SDK 安装代码。
|
||
|
||
步骤三：安装 SDK
|
||
你可以直接在页面中通过 script 标签的形式加载 Chat SDK 的 js 代码，将步骤二中复制好的安装代码粘贴到网页的 <body> 区域中即可。
|
||
步骤二中复制好的安装代码示例如下：
|
||
|
||
示例代码中的版本号 1.2.0-beta.15 为示例，请以 Chat SDK 最新的版本号为准，版本信息请参见Chat SDK 发布历史。
|
||
|
||
步骤四：配置聊天框
|
||
安装 Chat SDK 后，您现在可以初始化客户端。在页面中通过调用 CozeWebSDK.WebChatClient 来生成聊天框，当前页面中聊天框包括 PC 和移动端两种布局样式。在 PC 端中，聊天框位于页面右下角，移动端聊天框会铺满全屏。
|
||
智能体配置
|
||
调用 CozeWebSDK.WebChatClient 时，你需要配置以下参数：
|
||
config：必选参数，表示智能体的配置信息。
|
||
智能体需要设置的参数如下：
|
||
参数
|
||
是否必选
|
||
数据类型
|
||
描述
|
||
type
|
||
必选
|
||
String
|
||
Chat SDK 调用的对象。 在调用智能体时，该参数保持默认值 bot。
|
||
botId
|
||
必选
|
||
String
|
||
智能体的 ID。在智能体编排页面的 URL 中，查看 bot 关键词之后的字符串就是智能体 ID。例如https://www.coze.cn/space/341****/bot/73428668*****，智能体 ID 为 73428668*****。
|
||
isIframe
|
||
可选
|
||
Boolean
|
||
是否使用 iframe方式来打开聊天框，默认为 false。
|
||
true：使用 iframe 打开聊天框。
|
||
false（推荐）：非 iframe 方式打开聊天框。通过该方式可以规避小程序中 webview 的域名限制。
|
||
Chat SDK 1.2.0-beta.3 及以上版本支持该参数。
|
||
|
||
botInfo.parameters
|
||
可选
|
||
Map[String, Any]
|
||
给智能体中的自定义参数赋值并传给对话流。
|
||
如果在对话流的开始节点设置了自定义输入参数，你可以通过 parameters 参数指定自定义参数的名称和值，ChatSDK 会将自定义参数的值传递给对话流。具体用法和示例代码可参考为自定义参数赋值。
|
||
仅单 Agent（对话流模式）的智能体支持该配置。
|
||
|
||
|
||
auth：表示鉴权方式。当未配置此参数时表示不鉴权。为了账号安全，建议配置鉴权，请将 auth.type 设置为 token，在 token 参数中指定相应的访问密钥，并通过 onRefreshToken 监听获取新的密钥，当 token 中设置的访问密钥失效时，Chat SDK 能够自动重新获取新的密钥。调试场景可以直接使用准备工作中添加的访问密钥，快速体验 Chat SDK 的效果；正式上线时建议通过 SAT 或 OAuth 实现鉴权逻辑，并将获取的 OAuth 访问密钥填写在此处。
|
||
示例如下：
|
||
const cozeWebSDK = new CozeWebSDK.WebChatClient({
|
||
config: {
|
||
// 智能体 ID
|
||
botId: '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_zxzSAzxawer234zASNElEglZxcmWJ5ouCcq12gsAAsqJGALlq7hcOqMcPFV3wEVDiqjrg****',
|
||
}
|
||
});
|
||
|
||
如果要实现不同业务侧用户的会话隔离，即每个用户只能看到自己和智能体的对话历史，你需要将鉴权方式配置为 OAuth JWT 鉴权，通过 session_name 参数实现会话隔离，具体请参见如何实现会话隔离。
|
||
|
||
扣子应用配置
|
||
调用 CozeWebSDK.WebChatClient 时，你需要配置以下参数：
|
||
config：必选参数，表示应用的配置信息。
|
||
参数
|
||
是否必选
|
||
数据类型
|
||
描述
|
||
type
|
||
必选
|
||
String
|
||
Chat SDK 调用的对象。 集成扣子应用时，应设置为 app，表示通过 Chat SDK 调用扣子应用。
|
||
isIframe
|
||
非必选
|
||
Boolean
|
||
是否使用 iframe方式来打开聊天框，默认为 true。
|
||
true：使用 iframe 打开聊天框。
|
||
false（推荐）：非 iframe 方式打开聊天框。通过该方式可以规避小程序中 webview 的域名限制。
|
||
Chat SDK 1.2.0-beta.3 及以上版本支持该参数。
|
||
|
||
appInfo
|
||
必选
|
||
String
|
||
扣子应用的详细信息。
|
||
确保该应用已经发布为 Chat SDK。
|
||
|
||
appInfo.appId
|
||
必选
|
||
String
|
||
AI 应用的 ID。 在扣子应用中打开工作流或对话流，URL 中 project-ide 参数之后的字符串就是 appId。
|
||
appInfo.workflowId
|
||
必选
|
||
String
|
||
工作流或对话流的 ID。 在扣子应用中打开工作流或对话流，URL 中 workflow 参数之后的字符串就是 workflowId。
|
||
appInfo.parameters
|
||
可选
|
||
Map[String, Any]
|
||
给应用中的自定义参数赋值并传给对话流。
|
||
如果在对话流的开始节点设置了自定义输入参数，你可以通过 parameters 参数指定自定义参数的名称和值，ChatSDK 会将自定义参数的值传递给对话流。具体用法和示例代码可参考为自定义参数赋值。
|
||
|
||
auth：表示鉴权方式。当未配置此参数时表示不鉴权。为了账号安全，建议配置鉴权，请将 auth.type 设置为 token，在 token 参数中指定相应的访问密钥，并通过 onRefreshToken 监听获取新的密钥，当 token 中设置的访问密钥失效时，Chat SDK 能够自动重新获取新的密钥。调试场景可以直接使用准备工作中添加的访问密钥，快速体验 Chat SDK 的效果；正式上线时建议通过 SAT 或 OAuth 实现鉴权逻辑，并将获取的 OAuth 访问密钥填写在此处。
|
||
示例如下：
|
||
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****',
|
||
}
|
||
});
|
||
|
||
步骤五：配置属性
|
||
扣子 Chat SDK 支持多种属性配置，开发者可以按需调整对话框的多种展示效果，例如展示的用户信息、对话框 UI 效果、悬浮球展示、底部文案等。
|
||
你可以在 WebChatClient 方法中添加各种属性，实现对应的效果。目前支持的属性如下：
|
||
功能
|
||
属性
|
||
说明
|
||
智能体配置
|
||
config
|
||
指定对话的智能体或扣子应用，支持设置是否使用 iframe方式来打开聊天框
|
||
鉴权
|
||
auth
|
||
指定鉴权方式。默认不鉴权，支持通过 PAT 、SAT 或 OAuth 鉴权。
|
||
用户信息
|
||
userInfo
|
||
用于设置对话框中的显示用户信息，包括对话框中的用户头像、用户昵称、用户的业务 ID。
|
||
UI 效果
|
||
ui.base
|
||
用于添加聊天窗口的整体 UI 效果，包括应用图标、页面展示模式（移动端或 PC 端）、系统语言属性、聊天框页面层级。
|
||
悬浮球
|
||
ui.asstBtn
|
||
控制是否在页面右下角展示悬浮球。默认展示，用户点击悬浮球后将弹出聊天窗口。
|
||
底部文案
|
||
ui.footer
|
||
隐藏底部文案或改为其他文案，支持在文案中设置超链接。
|
||
顶部标题栏配置
|
||
ui.header
|
||
用于控制是否展示顶部的标题栏和关闭按钮，默认展示。
|
||
聊天框
|
||
ui.chatBot
|
||
用于控制聊天框的 UI 和基础能力，包括：
|
||
标题、大小、位置等基本属性
|
||
限制在聊天框中上传文件、语音输入、显示工具调用信息
|
||
|
||
步骤六：销毁客户端
|
||
你可以添加一个 destroy 方法销毁客户端。
|
||
<script>
|
||
const client = new CozeWebSDK.WebChatClient(options);
|
||
client.destroy();
|
||
</script>
|
||
|
||
属性配置
|
||
智能体或应用配置
|
||
config 参数用于指定智能体。智能体需要设置的参数如下：
|
||
参数
|
||
是否必选
|
||
数据类型
|
||
描述
|
||
bot_id
|
||
必选
|
||
String
|
||
智能体 ID。
|
||
进入智能体的开发页面，开发页面 URL 中 bot 参数后的数字就是智能体ID。例如https://www.coze.cn/space/341****/bot/73428668*****，智能体ID 为 73428668*****。
|
||
确保该智能体已经发布为 Chat SDK。
|
||
|
||
isIframe
|
||
非必选
|
||
Boolean
|
||
是否使用 iframe方式来打开聊天框，默认为 true。
|
||
true：使用 iframe 打开聊天框。
|
||
false（推荐）：非 iframe 方式打开聊天框。通过该方式可以规避小程序中 webview 的域名限制。
|
||
Chat SDK 1.2.0-beta.3 及以上版本支持该参数。
|
||
|
||
扣子应用需要设置的参数如下：
|
||
参数
|
||
是否必选
|
||
数据类型
|
||
描述
|
||
type
|
||
必选
|
||
String
|
||
Chat SDK 调用的对象。
|
||
默认为 bot，表示通过 Chat SDK 调用智能体。
|
||
集成扣子应用时，应设置为 app，表示通过 Chat SDK 调用扣子应用。
|
||
appInfo
|
||
必选
|
||
String
|
||
扣子应用的详细信息。
|
||
确保该应用已经发布为 Chat SDK。
|
||
|
||
appInfo.appId
|
||
必选
|
||
String
|
||
AI 应用 ID。 在扣子应用中打开工作流或对话流，URL 中 project-ide 参数之后的字符串是 appId。
|
||
appInfo.workflowId
|
||
必选
|
||
String
|
||
工作流或对话流 ID。 在扣子应用中打开工作流或对话流，URL 中 workflow 参数之后的字符串是 workflowId。
|
||
isIframe
|
||
非必选
|
||
Boolean
|
||
是否使用 iframe方式来打开聊天框，默认为 true。
|
||
true：使用 iframe 打开聊天框。
|
||
false（推荐）：非 iframe 方式打开聊天框。通过该方式可以规避小程序中 webview 的域名限制。
|
||
Chat SDK 1.2.0-beta.3 及以上版本支持该参数。
|
||
|
||
鉴权
|
||
auth 属性用于配置鉴权方式。不添加此参数时表示不鉴权，也可以通过此参数指定使用 PAT 或 OAuth 鉴权。配置说明如下：
|
||
参数
|
||
数据类型
|
||
是否必选
|
||
描述
|
||
type
|
||
String
|
||
|
||
必选
|
||
可指定为 token，通过访问密钥鉴权，支持的访问密钥包括 PAT、SAT 和 OAuth 访问密钥。关于访问密钥的详细说明可参考鉴权方式概述。
|
||
token
|
||
|
||
String
|
||
type为 token 时必填
|
||
type 为 token 时，指定使用的访问密钥。调试场景可以直接使用准备工作中添加的访问密钥，快速体验 Chat SDK 的效果；正式上线时建议通过 SAT 或 OAuth 实现鉴权逻辑，并将获取的 OAuth 访问密钥填写在此处。
|
||
onRefreshToken
|
||
Function
|
||
type为 token 时必填
|
||
token 中设置的访问密钥失效时，使用新密钥。建议按需设置。
|
||
|
||
以使用 PAT 鉴权为例，配置鉴权的方式如下：
|
||
const cozeWebSDK = new CozeWebSDK.WebChatClient({
|
||
config: {
|
||
botId: '740849137970326****',
|
||
isIframe: false,
|
||
},
|
||
auth: {
|
||
type: 'token',
|
||
token: 'pat_zxzSAzxawer234zASNElEglZxcmWJ5ouCcq12gsAAsqJGALlq7hcOqMcPFV3wEVDiqjrg****',
|
||
onRefreshToken: async () => 'pat_zxzSAzxawer234zASNElEglZxcmWJ5ouCcq12gsAAsqJGALlq7hcOqMcPFV3wEVDiqjrg****',
|
||
}
|
||
});
|
||
|
||
以使用 OAuth 鉴权为例，配置鉴权的方式如下：
|
||
const cozeWebSDK = new CozeWebSDK.WebChatClient({
|
||
config: {
|
||
botId: '740849137970326****',
|
||
isIframe: false,
|
||
},
|
||
auth: {
|
||
type: 'token',
|
||
token: 'czs_RQOhsc7vmUzK4bNgb7hn4wqOgRBYAO6xvpFHNbnl6RiQJX3cSXSguIhFDzgy****',
|
||
onRefreshToken: async () => 'czs_RQOhsc7vmUzK4bNgb7hn4wqOgRBYAO6xvpFHNbnl6RiQJX3cSXSguIhFDzgy****',
|
||
}
|
||
});
|
||
|
||
用户信息
|
||
userInfo 参数用于设置对话框中的显示用户信息，包括对话框中的用户头像和账号。同时，此处指定的用户 ID 也会通过发起对话 API 传递给扣子服务端。
|
||
参数
|
||
数据类型
|
||
是否必选
|
||
描述
|
||
url
|
||
String
|
||
必选
|
||
用户头像的 URL 地址，必须是一个可公开访问的地址。
|
||
nickname
|
||
String
|
||
必选
|
||
用户的昵称。
|
||
id
|
||
String
|
||
可选
|
||
用户的 ID，也就是用户在你的网站或应用中的账号 ID。未指定 ID 时，Chat SDK 会根据用户使用的设备随机分配一个用户 ID。
|
||
你可以在智能体的分析 > 消息链路页面查看不同用户 ID 的对话记录。详细说明可参考消息日志。
|
||
|
||
配置示例如下：
|
||
const cozeWebSDK = new CozeWebSDK.WebChatClient({
|
||
config: {
|
||
botId: '740849137970326****',
|
||
isIframe: false,
|
||
},
|
||
auth: {
|
||
type: 'token',
|
||
token: 'pat_zxzSAzxawer234zASNElEglZxcmWJ5ouCcq12gsAAsqJGALlq7hcOqMcPFV3wEVDiqjrg****',
|
||
onRefreshToken: async () => 'pat_zxzSAzxawer234zASNElEglZxcmWJ5ouCcq12gsAAsqJGALlq7hcOqMcPFV3wEVDiqjrg****',
|
||
},
|
||
// 用户信息
|
||
userInfo: {
|
||
id: '12345',
|
||
url: 'https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/obric/coze/favicon.1970.png',
|
||
nickname: 'UserA',
|
||
},
|
||
});
|
||
|
||
UI 效果
|
||
ui.base 参数用于添加聊天窗口的整体 UI 效果，包括应用图标、页面展示模式、语言属性等。
|
||
参数
|
||
数据类型
|
||
是否必选
|
||
描述
|
||
icon
|
||
String
|
||
可选
|
||
应用图标，必须是一个可访问的公开 URL 地址。如果不设置，则使用默认扣子图标。
|
||
扣子企业版支持将 icon 修改为自定义的品牌 Logo，扣子团队版和个人版不支持自定义品牌。
|
||
|
||
layout
|
||
|
||
String
|
||
可选
|
||
聊天框窗口的布局风格，支持设置为：
|
||
mobile：移动端风格，聊天框窗口铺满移动设备全屏。
|
||
pc：PC 端风格，聊天框窗口位于页面右下角。
|
||
未设置此参数时，系统会自动识别设备，设置相应的布局风格。
|
||
lang
|
||
String
|
||
可选
|
||
系统语言，例如工具提示信息的语言。
|
||
en：（默认）英语
|
||
zh-CN：中文
|
||
zIndex
|
||
number
|
||
可选
|
||
开发者自行控制，用于调整聊天框的页面层级。详细信息可参考MDN-zIndex。
|
||
|
||
示例代码如下：
|
||
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: '3qweqweqwe',
|
||
},
|
||
ui: {
|
||
base: {
|
||
icon: 'https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/obric/coze/favicon.1970.png',
|
||
layout: 'pc',
|
||
zIndex: 1000,
|
||
}
|
||
},
|
||
});
|
||
|
||
悬浮球
|
||
asstBtn 参数用于控制是否在页面右下角展示悬浮球。默认展示，用户点击悬浮球后将弹出聊天窗口。
|
||
|
||
若设置为不展示悬浮球，开发者需要通过以下方法控制聊天框的展示或隐藏效果。
|
||
显示聊天框：cozeWebSDK.showChatBot()
|
||
隐藏聊天框：cozeWebSDK.hideChatBot()
|
||
参数
|
||
数据类型
|
||
是否必选
|
||
描述
|
||
isNeed
|
||
boolean
|
||
否
|
||
|
||
是否在页面右下角展示悬浮球。
|
||
true：（默认）展示悬浮球。
|
||
false：不展示悬浮球。
|
||
|
||
以不展示悬浮球为例，示例代码如下：
|
||
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: '3qweqweqwe',
|
||
},
|
||
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: false,
|
||
},
|
||
},
|
||
});
|
||
|
||
不展示悬浮球时，你可以通过以下方式显示聊天框或隐藏聊天框。
|
||
<body>
|
||
<button onClick={() => {
|
||
cozeWebSDK.showChatBot();
|
||
}}>显示聊天框</button>
|
||
<button onClick={() => {
|
||
cozeWebSDK.hideChatBot();
|
||
}}>隐藏聊天框</button>
|
||
</body>
|
||
|
||
底部文案
|
||
聊天框底部会展示对话服务的提供方信息，默认为Powered by coze. AI-generated content for reference only.。开发者通过 footer 参数隐藏此文案或改为其他文案，支持在文案中设置超链接。
|
||
底部文案默认展示效果如下：
|
||
|
||
footer 参数配置说明如下：
|
||
参数
|
||
数据类型
|
||
是否必选
|
||
描述
|
||
isShow
|
||
boolean
|
||
可选
|
||
是否展示底部文案模块。
|
||
true：展示。此时需要通过 expressionText 和 linkvars 设置具体文案和超链接。
|
||
false：不展示。expressionText 和 linkvars 设置不生效。
|
||
expressionText
|
||
String
|
||
可选
|
||
底部显示的文案信息。支持添加以下格式的内容：
|
||
纯文本：直接输入文本信息。
|
||
链接：通过双大括号（{{***}} ）设置链接。双大括号中的字段会被替换 linkvars中的内容替换掉。仅支持设置一个链接。
|
||
linkvars
|
||
Object
|
||
可选
|
||
底部文案中的链接文案与链接地址。
|
||
替换规则：name与"{{***}}"中的字段保持对应关系，同时用 a 标签替换掉该文本，text 为 a 标签的文案，link 为跳转的链接地址。
|
||
|
||
配置示例如下：
|
||
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: '3qweqweqwe',
|
||
},
|
||
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、及关闭按钮。展示效果类似如下：
|
||
|
||
Chat SDK 1.1.0-beta.3 及以上版本支持该配置。
|
||
|
||
您可以通过 header 参数配置是否展示顶部标题栏和关闭按钮，header 参数配置说明如下：
|
||
参数
|
||
数据类型
|
||
是否必选
|
||
描述
|
||
isShow
|
||
Boolean
|
||
可选
|
||
是否展示顶部标题栏，默认为 true。
|
||
true：展示。
|
||
false：不展示。
|
||
isNeedClose
|
||
String
|
||
可选
|
||
是否展示顶部的关闭按钮，默认为 true。
|
||
true：展示。
|
||
false：不展示。
|
||
|
||
配置示例如下：
|
||
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: '3qweqweqwe',
|
||
},
|
||
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
|
||
可选
|
||
聊天框的标题，若未配置，使用默认名称 Coze Bot。
|
||
uploadable
|
||
Boolean
|
||
可选
|
||
是否开启聊天框的上传能力。
|
||
true：（默认）聊天框支持上传文件。选择此选项时，应确认模型具备处理文件或图片的能力，例如使用的是多模态模型，或添加了多模态插件。
|
||
false：聊天框不支持上传文件。
|
||
width
|
||
Number
|
||
可选
|
||
PC 端窗口的宽度，单位为 px，默认为 460。
|
||
建议综合考虑各种尺寸的屏幕，设置一个合适的宽度。
|
||
此配置仅在 PC 端且未设置 el 参数时生效。
|
||
el
|
||
Element
|
||
可选
|
||
设置聊天框放置位置的容器（Element）。
|
||
开发者应自行设置聊天框高度、宽度，聊天框会占满整个元素空间。
|
||
Chat SDK 会自动控制聊天框的显示隐藏，但是对于宿主的 element 元素不会做控制，开发者按需在 onHide、onShow 回调时机中来控制宿主元素的显示隐藏。
|
||
isNeedAudio
|
||
Boolean
|
||
可选
|
||
设置聊天框中是否允许语音输入。
|
||
true：支持用户通过语音输入。
|
||
false：仅支持打字输入，不支持语音输入。
|
||
默认值：
|
||
非 Iframe 模式（聊天框集成在主页面中）： 默认值为 true。
|
||
ifreme 模式（聊天框作为独立窗口嵌入主页面）： 默认值为 false。
|
||
|
||
isNeedFunctionCallMessage
|
||
Boolean
|
||
可选
|
||
设置是否在聊天框中显示插件工具调用的信息。
|
||
true：（默认值）聊天框中将显示调用的插件工具。
|
||
false：聊天框中不显示插件工具调用的信息。
|
||
|
||
相关回调：
|
||
onHide：当聊天框隐藏的时候，会回调该方法。
|
||
onShow: 当聊天框显示的时候，会回调该方法。
|
||
onBeforeShow: 聊天框显示前调用，如果返回了 false，则不会显示。支持异步函数。
|
||
onBeforeHide: 聊天框隐藏前调用，如果返回了 false，则不会隐藏。支持异步函数。
|
||
在以下示例中，聊天框标题为 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: '3qweqweqwe',
|
||
},
|
||
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,
|
||
onHide: () => {
|
||
// todo...
|
||
},
|
||
onShow: () => {
|
||
// todo...
|
||
},
|
||
},
|
||
},
|
||
});
|
||
|
||
通过 chatbot 的 el 参数设置组件的示例代码如下：
|
||
|
||
相关操作
|
||
更新 SDK 版本
|
||
扣子 Chat SDK 将持续更新迭代，支持丰富的对话能力和展示效果。你可以在 Chat SDK 的 script 标签中指定 Chat SDK 的最新版本号，体验和使用最新的 Chat SDK 对话效果。
|
||
在以下代码中，将 {{version}} 部分替换为 Chat SDK 的最新版本号。你可以在Chat SDK 发布历史中查看最新版本号。
|
||
|
||
解绑 Chat SDK
|
||
如果不再需要通过 Chat SDK 使用 AI 应用，可以在发布页面点击解绑按钮。一旦解绑，智能体或应用就无法通过集成的 Web 应用程序使用。 如果您想恢复 Web 应用程序的访问，需要再次将智能体或应用发布为 Chat SDK。
|
||
|
||
示例
|
||
以下是一段完整的 Chat SDK 调用智能体的代码示例。
|
||
<!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.2.0-beta.8/libs/cn/index.js"></script>
|
||
<script>
|
||
const cozeWebSDK = new CozeWebSDK.WebChatClient({
|
||
config: {
|
||
// 智能体 ID
|
||
botId: '742477211246629****',
|
||
},
|
||
auth: {
|
||
//鉴权方式，默认type 为unauth，表示不鉴权；建议设置为 token，表示通过PAT或OAuth鉴权
|
||
type: 'token',
|
||
//type 为 token 时，需要设置PAT或OAuth访问密钥
|
||
token: 'pat_82GrrdfNWPMnlcY58r98Rzqiev2s5NyrqCR8Ypbh5hOomzZN4ivb325PZAd****',
|
||
//访问密钥过期时，使用的新密钥，可以按需设置。
|
||
onRefreshToken: () => 'pat_82GrrdfNWPMnlcY58r98Rzqiev2s5NyrqCR8Ypbh5hOomzZN4ivb325PZAdZ****',
|
||
},ui:{
|
||
chatBot: {
|
||
title: "智能客服",
|
||
uploadable: true
|
||
}}
|
||
});
|
||
</script>
|
||
</body>
|
||
</html>
|
||
|
||
相关文档 |