> ## Documentation Index > Fetch the complete documentation index at: https://docs.coze.cn/llms.txt > Use this file to discover all available pages before exploring further. 本文介绍如何安装并使用扣子 Chat SDK，开发者可以参考本文档在自己开发的网站或 App 中快速实现智能对话功能。适用于智能客服、答疑助手或企业内部的 IT 支持机器人等场景。 ## 前置条件 {#42f5b09f} ### 浏览器兼容性 {#c73a3841} Chat SDK 的运行环境要求如下表所示。 | | | \ |**浏览器** |**版本限制** | |---|---| | | | \ |Chrome | 87.0 及以上 | | | | \ |Edge | 88.0 及以上 | | | | \ |Safari | 14.0 及以上 | | | | \ |Firefox | 78.0 及以上 | ### 获取访问密钥 {#46872912} 访问密钥用于 Chat SDK 的身份认证与鉴权。根据使用场景选择合适的鉴权方式，各鉴权方式的区别请参见[鉴权方式概述](/developer_guides/authentication)。 | | | | | \ |**场景** |**推荐方案** |**说明** |**参考文档** | |---|---|---|---| | | | | | \ |开发调试 |个人访问令牌（PAT） |快速跑通 Chat SDK 的整体流程。 |[添加个人访问令牌](/developer_guides/pat) | | | | | | \ |生产环境 |服务访问令牌（SAT） |操作更简单，能够有效简化授权流程，适合需要长期稳定访问且无需进行会话隔离的场景。 |\ | | |**仅企业版（企业标准版、企业旗舰版）支持使用 SAT 鉴权。** |[添加服务访问令牌](/developer_guides/service_token) | |^^| | | | \ | |OAuth 鉴权 |支持渠道用户访问智能体、会话隔离（即智能体不同账号的消息内容互相隔离）。 |[OAuth 应用管理](/developer_guides/oauth_apps) |\ | | | |[OAuth JWT 授权（渠道场景）](/developer_guides/oauth_jwt_channel) | ### 权限要求 {#42f5efb2} 访问密钥需被授予以下权限，才能正常使用 Chat SDK 的各项能力。Chat SDK 所需的权限列表如下： | | | | \ |**密钥类型** |**PAT /** **SAT /普通 OAuth** | **渠道 OAuth 访问密钥** | |---|---|---| | | | | \ |权限点 |\ | |* Bot管理 |\ | | * chat |\ | | * getMetadata |\ | |* 会话管理 |\ | | * listConversation |\ | | * createConversation |\ | | * editConversation |\ | |* 对话 |\ | | * cancelChat |\ | |* 工作流 |\ | | * getMetadata |\ | |* 应用管理 |\ | | * getMetadata |\ | |* 文件 |\ | | * uploadFile |\ | |* 消息 |\ | | * listMessage |\ | |* 智能音视频 |\ | | * createTranscription |\ | | * createSpeech |* botChat |\ | | |* getMetadata |\ | | |* listConversation |\ | | |* createConversation |\ | | |* editConversation |\ | | |* uploadFile |\ | | |* listConversationMessage |\ | | |* cancelConversationChat |\ | | |* createTranscription |\ | | |* createSpeech |\ | | | |\ | | | | :::tip 说明 渠道 OAuth 访问密钥的权限点是渠道类型的 OAuth 应用中设置的权限点，创建应用并授权的详细说明可参考[OAuth JWT 授权（渠道场景）](/developer_guides/oauth_jwt_channel)。 ::: ## 调试与体验 Chat SDK {#e6b680be} 你可以通过 [Playground](https://www.coze.cn/open/playground/chatsdk) 调试与体验 Chat SDK 各配置项的功能和效果。 ![Image=600x453](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/2ac0e8fe7fdb4184800a12c270a52494~tplv-goo7wpa0wc-image.image) ## 配置流程 {#30cdf1b4} ### 步骤一：发布智能体或扣子应用 {#8e6d2c3c} 在智能体或 AI 应用的发布页面，选择 Chat SDK，并单击**发布**。发布的详细流程可参考： * [发布为 Chat SDK](/guides/publish_app_to_web_sdk) * [发布到 Chat SDK](/guides/publish_agent_to_chat_sdk) ### 步骤二：获取安装代码 {#b674a449} 进入发布页面复制 SDK 安装代码。 :::: tabs @tab 智能体 1. 在智能体的编排页面，单击**发布**，进入**发布**页面。 2. 在**发布**页面，单击**安装**。 页面将展示安装代码，安装代码中默认使用最新版本的 Chat SDK 配置。 ![Image=600x103](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/600644e03dde45ae983b190b7a9e227c~tplv-goo7wpa0wc-image.image) 3. 复制此安装代码。 ![Image=500x443](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/bfc914429f7d4fd4a4507b580d2cc4e8~tplv-goo7wpa0wc-image.image) 请妥善保存此代码用于步骤三。 @tab 扣子应用 1. 在扣子应用的编排页面右上角，单击发布下拉按钮查看指定版本的发布状态。 2. 确认 Chat SDK 发布成功后，单击**安装指引**。 ![Image=600x317](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/d71084f8d6d04b7c9daf641ad3115052~tplv-goo7wpa0wc-image.image) 3. 根据页面提示复制安装代码。此代码将在后续的配置中使用。 ![Image=281x167](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/8472489162894109abc129a16f3aa653~tplv-goo7wpa0wc-image.image) :::: ### 步骤三：安装 SDK {#51d9228d} 将步骤二中复制的安装代码粘贴到网页中，例如 标签内，通过 `script` 标签加载 Chat SDK 的 js 代码。 示例代码如下： :::: tabs @tab 智能体 ```HTML ``` @tab 扣子应用 ```HTML ``` :::: :::tip 说明 示例代码中的版本号 `1.2.0-beta.20 `为示例，请以 Chat SDK 最新的版本号为准，版本信息请参见[Chat SDK 发布历史](/developer_guides/web_sdk_changelog)。 ::: ### 步骤四：初始化配置 {#d62ce46b} 通过调用 CozeWebSDK.WebChatClient 初始化客户端。当前页面中聊天框包括 PC 和移动端两种布局样式，在 PC 端中，聊天框位于页面右下角，移动端聊天框会铺满全屏。 #### 智能体配置 {#b904605f} 调用 CozeWebSDK.WebChatClient 时，你需要配置 `config`（智能体信息）和 `auth`（鉴权信息）。 * **config**：必选参数，表示智能体的配置信息。 调用智能体时，需要设置以下参数： | | | | | \ |**参数** |**是否必选** |**数据类型** |**描述** | |---|---|---|---| | | | | | \ |type |必选 |String | Chat SDK 调用的对象。 在调用智能体时，该参数保持默认值 **bot**。 |\ | | | | |\ | | | |* `bot`：（默认值）智能体。 |\ | | | |* `app`：扣子应用。 | | | | | | \ |bot_id |必选 |String |智能体的 ID。在智能体编排页面的 URL 中，查看 **bot** 关键词之后的字符串就是智能体 ID。例如`https://www.coze.cn/space/341****/bot/73428668*****`，智能体 ID 为 `73428668*****`。 | | | | | | \ |isIframe |可选 |Boolean |是否使用 iframe方式来打开聊天框，默认为 false。 |\ | | | | |\ | | | |* `true`：使用 iframe 方式打开聊天框。聊天框内容在独立的 iframe 窗口中运行。 |\ | | | |* `false`（推荐）：聊天框直接集成到你的网页中，与网页共用一个运行环境。可以规避小程序对跨域名的限制。 | | | | | | \ |botInfo.parameters |可选 |Map[String, Any] |给智能体中的自定义参数赋值并传给对话流。 |\ | | | |如果在对话流的开始节点设置了自定义输入参数，你可以通过 `parameters` 参数指定自定义参数的名称和值，ChatSDK 会将自定义参数的值传递给对话流。具体用法和示例代码可参考[为自定义参数赋值](/tutorial/variable)。 |\ | | | |:::tip 说明 |\ | | | |仅**单 Agent（对话流模式）​**的智能体支持该配置。 |\ | | | |::: | * **auth**：表示鉴权方式。当未配置此参数时表示不鉴权。为了账号安全，建议配置鉴权。 | | | | | \ |**参数** |**数据类型** |**是否必选** |**描述** | |---|---|---|---| | | | | | \ |type |String |\ | | |必选 |可指定为 `token`，通过访问密钥鉴权，支持的访问密钥包括 PAT、SAT 和 OAuth 访问密钥。关于访问密钥的详细说明可参考[鉴权方式概述](/developer_guides/authentication)。 | | | | | | \ |token |\ | |String |type为 token 时必填 |`type` 为 `token` 时，指定使用的访问密钥。 |\ | | | | |\ | | | |* 调试场景可以直接使用个人访问令牌（PAT），快速体验 Chat SDK 的效果。 |\ | | | |* 正式上线时建议通过 SAT 或 OAuth 实现鉴权逻辑，并将获取的 OAuth 访问密钥填写在此处。 | | | | | | \ |onRefreshToken |Function |type为 token 时必填 |在对话过程中，当检测到访问密钥（token）失效时，将自动使用设置的新密钥。 |\ | | | |触发前可能会导致最近一次请求失败，并产生一条错误记录。刷新成功后，后续请求将恢复正常。 | 初始化示例如下： ```TypeScript 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****', } }); ``` :::tip 说明 如果要实现不同业务侧用户的会话隔离，即每个用户只能看到自己和智能体的对话历史，你需要将鉴权方式配置为 OAuth JWT 鉴权，通过 session_name 参数实现会话隔离，具体请参见[如何实现会话隔离](/developer_guides/session_isolation)。 ::: #### 扣子应用配置 {#5257fbe4} 调用 CozeWebSDK.WebChatClient 时，你需要配置扣子应用的基础信息以及鉴权参数： * **config**：必选参数，表示应用的配置信息。 | | | | | \ |**参数** |**是否必选** |**数据类型** |**描述** | |---|---|---|---| | | | | | \ |type |必选 |String | Chat SDK 调用的对象。 集成扣子应用时，应设置为 **app**，表示通过 Chat SDK 调用扣子应用。 | | | | | | \ |isIframe |非必选 |Boolean |是否使用 iframe方式来打开聊天框，默认为 `true`。 |\ | | | | |\ | | | |* `true`：使用 iframe 方式打开聊天框。聊天框内容在独立的 iframe 窗口中运行。 |\ | | | |* `false`（推荐）：聊天框直接集成到你的网页中，与网页共用一个运行环境。可以规避小程序对跨域名的限制。 | | | | | | \ |appInfo |必选 |Object |扣子应用的详细信息。 |\ | | | |:::tip 说明 |\ | | | |确保该应用已经发布为 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 会将自定义参数的值传递给对话流。具体用法和示例代码可参考[为自定义参数赋值](/tutorial/variable)。 | * **auth**：表示鉴权方式。当未配置此参数时表示不鉴权。为了账号安全，建议配置鉴权。 | | | | | \ |**参数** |**数据类型** |**是否必选** |**描述** | |---|---|---|---| | | | | | \ |type |String |\ | | |必选 |可指定为 `token`，通过访问密钥鉴权，支持的访问密钥包括 PAT、SAT 和 OAuth 访问密钥。关于访问密钥的详细说明可参考[鉴权方式概述](/developer_guides/authentication)。 | | | | | | \ |token |\ | |String |type为 token 时必填 |`type` 为 `token` 时，指定使用的访问密钥。 |\ | | | | |\ | | | |* 调试场景可以直接使用个人访问令牌（PAT），快速体验 Chat SDK 的效果。 |\ | | | |* 正式上线时建议通过 SAT 或 OAuth 实现鉴权逻辑，并将获取的 OAuth 访问密钥填写在此处。 | | | | | | \ |onRefreshToken |Function |type为 token 时必填 |在对话过程中，当检测到访问密钥（token）失效时，将自动使用设置的新密钥。 |\ | | | |触发前可能会导致最近一次请求失败，并产生一条错误记录。刷新成功后，后续请求将恢复正常。 | 示例如下： ```TypeScript 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****', } }); ``` ### 步骤五：自定义聊天界面与交互 {#3dc45e38} 开发者可以按需调整对话框的多种展示效果，例如展示的用户信息、对话框 UI 效果、悬浮球展示、底部文案等。 你可以在 WebChatClient 方法中添加各种属性，实现对应的效果。目前支持的属性如下： | | | | \ |**功能** |**属性** |**说明** | |---|---|---| | | | | \ |[配置用户信息](/developer_guides/install_web_sdk#c29240ae) |userInfo |用于设置对话框中的显示用户信息，包括对话框中的用户头像、用户昵称、用户的业务 ID。 | | | | | \ |[基础 UI 配置](/developer_guides/install_web_sdk#5b477c71) |ui.base |用于配置聊天窗口的整体 UI 效果，包括应用图标、页面展示模式（移动端或 PC 端）、系统语言属性、聊天框页面层级。 | | | | | \ |[悬浮球](/developer_guides/install_web_sdk#21e02fd4) |ui.asstBtn |控制是否在页面右下角展示悬浮球。默认展示，用户点击悬浮球后将弹出聊天窗口。 | | | | | \ |[底部文案](/developer_guides/install_web_sdk#ef54b6b8) |ui.footer |隐藏底部文案或改为其他文案，支持在文案中设置超链接。 | | | | | \ |[顶部标题栏配置](/developer_guides/install_web_sdk#b1401715) |ui.header |用于控制是否展示顶部的标题栏和关闭按钮，默认展示。 | | | | | \ |[聊天框](/developer_guides/install_web_sdk#00462b89) |ui.chatBot |用于控制聊天框的 UI 和基础能力，包括： |\ | | | |\ | | |* 标题、大小、位置等基本属性。 |\ | | |* 在聊天框中是否支持上传文件、语音输入、显示工具调用信息、创建新会话功能、消息追问。 | | | | | \ |[消息评价](/developer_guides/install_web_sdk#a3803915) |ui.chatBot |配置是否允许用户对智能体的回答进行评价（点赞 / 点踩）。 | | | | | \ |[会话列表](/developer_guides/install_web_sdk#9b803e65) |ui.conversations | 配置是否启用会话列表功能。 | ### 步骤六：销毁客户端 {#ec8a67cf} 若需在页面卸载或特定场景下关闭 Chat SDK，可调用 `destroy` 方法销毁客户端，释放资源。 ```HTML ``` ## 自定义聊天界面与交互 {#b05eed92} 你可以配置对话框中的用户信息、布局、悬浮球、底部文案、顶部标题栏等 UI 元素，以满足品牌风格需求。 ### 配置用户信息 {#c29240ae} `userInfo` 参数用于设置对话框中显示的用户信息，包括对话框中的用户头像和用户昵称。同时，此处指定的用户 ID 也会通过[发起对话](/developer_guides/chat_v3) API 传递给扣子服务端。 ![Image=300x202](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/386d2c53533c4cdfa2acdf23390a67af~tplv-goo7wpa0wc-image.image) | | | | | | \ |**参数** |**数据类型** |**是否必选** |**示例** |**描述** | |---|---|---|---|---| | | | | | | \ |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（`user_id`）。 |\ | | | | |未指定 ID 时，Chat SDK 会根据用户使用的设备随机分配一个用户 ID。 |\ | | | | |你可以在智能体的**分析** > **消息链路**页面查看不同用户 ID 的对话记录。详细说明可参考[消息日志](/guides/queries)。 | 配置示例如下： ```TypeScript 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 配置 {#5b477c71} `ui.base` 参数用于添加聊天窗口的整体 UI 效果，包括应用图标、页面布局、语言属性等。 | | | | | | \ |**参数** |**数据类型** |**是否必选** |**示例** |**描述** | |---|---|---|---|---| | | | | | | \ |icon |String |可选 |https://example.com/obj/coze-web-cn/obric/coze/favicon.1970.png |应用图标，必须是一个可访问的公开 URL 地址。如果不设置，则使用默认扣子图标。 |\ | | | | |:::tip 说明 |\ | | | | |扣子企业旗舰版支持将 icon 修改为自定义的品牌 Logo，扣子团队版和个人版不支持自定义品牌。 |\ | | | | |::: | | | | | | | \ |layout |\ | |String |可选 |pc |聊天框窗口的布局风格，支持设置为： |\ | | | | | |\ | | | | |* `mobile`：移动端风格，聊天框窗口铺满移动设备全屏。 |\ | | | | |* `pc`：PC 端风格，聊天框窗口位于页面右下角。 |\ | | | | | |\ | | | | |未设置此参数时，系统会自动识别设备，设置相应的布局风格。 | | | | | | | \ |lang |String |可选 |zh-CN |系统语言，例如工具提示信息的语言。 |\ | | | | | |\ | | | | |* `en`：（默认）英语。 |\ | | | | |* `zh-CN`：中文。 | | | | | | | \ |zIndex |Number |可选 |1000 |用于控制聊天框在网页中的页面层级，避免被其他元素遮挡。值越大，显示在越上层。详细信息可参考[MDN-zIndex](https://developer.mozilla.org/zh-CN/docs/Web/CSS/z-index)。 | 示例代码如下： ```TypeScript // 在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, } }, }); ``` ### 悬浮球 {#21e02fd4} `ui.asstBtn` 参数用于控制是否在页面右下角展示悬浮球。默认展示，用户点击悬浮球后将弹出聊天窗口。 ![Image=431x239](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/20ad89c564e84d7d9817a38f49d10071~tplv-goo7wpa0wc-image.image) | | | | | | \ |**参数** |**数据类型** |**是否必选** |**示例** |**描述** | |---|---|---|---|---| | | | | | | \ |isNeed |Boolean |可选 |\ | | | |true |是否在页面右下角展示悬浮球。 |\ | | | | | |\ | | | | |* `true`：（默认）展示悬浮球。 |\ | | | | |* `false`：隐藏悬浮球。若设置为隐藏悬浮球，开发者需要通过以下方法控制聊天框的展示或隐藏效果。具体请参考下文的示例代码。 |\ | | | | | * **显示聊天框：​**cozeWebSDK.showChatBot() |\ | | | | | * **隐藏聊天框：​**cozeWebSDK.hideChatBot() | 示例代码如下： :::: tabs @tab 展示悬浮球 ```TypeScript // 在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 // 展示悬浮球 } } }); ``` @tab 隐藏悬浮球 ```TypeScript // 在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 // 隐藏悬浮球 } } }); ``` 隐藏悬浮球时，你可以通过以下方式显示聊天框或隐藏聊天框。 ```HTML ``` :::: Chat SDK 悬浮球的位置默认在页面右下角，不支持移动，如果需要调整悬浮球的位置，你可以隐藏默认的悬浮球，自定义悬浮球的位置和样式，具体请参见[Chat SDK 悬浮球位置如何移动？](/developer_guides/chat_sdk_faq#d5f79f31)。 ### 底部文案 {#ef54b6b8} 聊天框底部会展示对话服务的提供方信息，默认为`Powered by coze. AI-generated content for reference only.`。开发者通过 `ui.footer` 参数隐藏此文案或改为其他文案，支持在文案中设置超链接。 底部文案默认展示效果如下： ![Image=462x156](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/159ed23acb1542f08f7be99702b22bfa~tplv-goo7wpa0wc-image.image) `footer` 参数配置说明如下： | | | | | | \ |**参数** |**数据类型** |**是否必选** |**示例** |**描述** | |---|---|---|---|---| | | | | | | \ |isShow |Boolean |可选 |true |是否展示底部文案模块。 |\ | | | | | |\ | | | | |* `true`：展示。此时需要通过 `expressionText` 和 `linkvars` 参数设置具体文案和超链接。 |\ | | | | |* `false`：不展示底部文案。expressionText 和 linkvars 设置不生效。 | | | | | | | \ |expressionText |String |可选 |Powered by {{name}} {{name1}} |底部显示的文案信息。支持添加以下格式的内容： |\ | | | | | |\ | | | | |* **纯文本**：直接输入文本信息。 |\ | | | | |* **链接**：通过双大括号（`{{变量名}}` ）设置链接。`{{变量名}}` 会被 `linkvars` 中的内容替换为超链接。仅支持设置一个链接。 | | | | | | | \ |linkvars |Object |可选 |{ name: { text: 'A', link: 'https://www.test1.com' }, name1: { text: 'B', link: 'https://www.test2.com' } } |用于定义 `expressionText` 中 `{{变量名}}` 对应的链接详情，格式为键值对： |\ | | | | | |\ | | | | |* 键：需与 `expressionText` 中 `{{}}` 内的变量名完全一致。 |\ | | | | |* 值：对象，包含 `text`（链接显示的文字，如示例中的 `A`）和 `link`（链接跳转地址，如示例中的`https://www.test1.com`）。 |\ | | | | | |\ | | | | |替换后示例： |\ | | | | |`Powered by A B` | 配置示例如下： ```TypeScript 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' } } } } }, }); ``` 此配置的对应的展示效果如下： ![Image=458x169](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/1bfd1682942f4e7988b863ac5a3dde26~tplv-goo7wpa0wc-image.image) ### 顶部标题栏配置 {#b1401715} 聊天框顶部默认展示智能体名称、icon 及关闭按钮。展示效果类似如下： ![Image=600x77](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/603868ce02ca4cbb8c0e0f89fc170d4b~tplv-goo7wpa0wc-image.image) 您可以通过 `ui.header` 参数配置是否展示顶部标题栏和关闭按钮，header 参数配置说明如下： | | | | | \ |**参数** |**数据类型** |**是否必选** |**描述** | |---|---|---|---| | | | | | \ |isShow |Boolean |可选 |是否展示顶部标题栏，默认为 true。 |\ | | | | |\ | | | |* `true`：展示。 |\ | | | |* `false`：不展示。 | | | | | | \ |isNeedClose |String |可选 |是否展示顶部的关闭按钮，默认为 true。 |\ | | | | |\ | | | |* `true`：展示。 |\ | | | |* `false`：不展示。 | 配置示例如下： ```TypeScript 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, }, }, }); ``` ### **聊天框** {#00462b89} `chatBot` 参数用于控制聊天框的 UI 和基础能力，包括标题、大小、位置等基本属性，还可以指定是否支持在聊天框中上传文件。此参数同时提供多个回调方法，用于同步聊天框显示、隐藏等事件通知。 配置说明如下： | | | | | | \ |**参数** |**数据类型** |**是否必选** |**示例** |**描述** | |---|---|---|---|---| | | | | | | \ |**title** |String |可选 |电商客服 |聊天框的标题，若未配置，使用默认名称 `Coze Bot`。 | | | | | | | \ |**uploadable** |Boolean |可选 |true |是否开启聊天框的上传能力。 |\ | | | | | |\ | | | | |* `true`：（默认）聊天框支持上传文件。选择此选项时，应确认模型具备处理文件或图片的能力，例如使用的是多模态模型，或添加了多模态插件。 |\ | | | | |* `false`：聊天框不支持上传文件。 | | | | | | | \ |**width** |Number |可选 |500 |PC 端窗口的宽度，单位为 px，默认为 460。 |\ | | | | |建议综合考虑各种尺寸的屏幕，设置一个合适的宽度。 |\ | | | | |此配置仅在 PC 端且未设置 `el` 参数时生效。 | | | | | | | \ |**el** |Element |可选 |见下文的示例代码 |设置聊天框放置位置的容器（Element）。 |\ | | | | | |\ | | | | |* 开发者应自行设置聊天框高度、宽度，聊天框会占满整个元素空间。 |\ | | | | |* Chat SDK 会自动控制聊天框的显示隐藏，但不会控制宿主的 element 元素，开发者按需在 onHide、onShow 回调中控制宿主元素的显示和隐藏。 | | | | | | | \ |**isNeedAudio** |Boolean |可选 |true |设置聊天框中是否允许语音输入。 |\ | | | | | |\ | | | | |* `true`：支持用户通过语音输入。 |\ | | | | |* `false`：仅支持打字输入，不支持语音输入。 |\ | | | | | |\ | | | | |默认值： |\ | | | | | |\ | | | | |* 非 Iframe 模式（聊天框集成在主页面中）： 默认值为 `true`。 |\ | | | | |* Iframe 模式（聊天框作为独立窗口嵌入主页面）： 默认值为 `false`。 |\ | | | | | |\ | | | | |![Image=200x131](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/33e4820fd23341ad8d87872f3cacbdba~tplv-goo7wpa0wc-image.image) | | | | | | | \ |**isNeedFunctionCallMessage** |Boolean |可选 |true |设置是否在聊天框中显示插件工具调用的信息。 |\ | | | | | |\ | | | | |* `true`：（默认值）聊天框中将显示调用的插件工具。 |\ | | | | |* `false`：聊天框中不显示插件工具调用的信息。 | | | | | | | \ |**isNeedAddNewConversation** |Boolean |可选 |true |设置是否在聊天框中显示**创建新会话**功能。 |\ | | | | | |\ | | | | |* `true`：聊天框右上角将显示**创建新会话**按钮，单击后即可创建新的会话。 |\ | | | | |* `false`：（默认值）聊天框右上角不显示**创建新会话**按钮。 |\ | | | | | |\ | | | | |![Image=200x118](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/2559cfaf58484104a50fe2be3db678d2~tplv-goo7wpa0wc-image.image) | | | | | | | \ |**isNeedQuote** |Boolean |可选 |true |设置是否支持对智能体或应用回复的消息进行追问。 |\ | | | | | |\ | | | | |* `true`：支持对消息进行追问。 |\ | | | | |* `false`：（默认值）不支持追问功能。 |\ | | | | | |\ | | | | |![Image=200x271](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/84a7fdd91fde4d068b976e7d931e9798~tplv-goo7wpa0wc-image.image) |\ | | | | |:::tip 说明 |\ | | | | |仅支持对返回的文本和图片消息进行追问，不支持对卡片和文件进行追问。 |\ | | | | |::: | 相关回调： * **onHide：​**当聊天框隐藏的时候，会回调该方法。 * **onShow:** 当聊天框显示的时候，会回调该方法。 * **onBeforeShow:** 聊天框显示前调用，如果返回了 false，则不会显示。支持异步函数。 * **onBeforeHide:** 聊天框隐藏前调用，如果返回了 false，则不会隐藏。支持异步函数。 在以下示例中，聊天框标题为 Kids' Playmate | Snowy，并开启上传文件功能。 ![Image=477x482](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/8bb924d3441a46e4a837c12edf0acdf0~tplv-goo7wpa0wc-image.image) 对应的代码示例如下： ```TypeScript 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 参数设置组件的示例代码如下： :::: tabs @tab index.html ```TypeScript
``` @tab index.js ```TypeScript 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(); } ``` :::: ### 消息评价 {#a3803915} 你可以在 `chatBot` 参数中配置是否允许用户对智能体的回答进行评价（点赞 / 点踩），默认禁用评价功能。 ![Image=600x565](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/14a8773b3f394440b78155a399ba59e6~tplv-goo7wpa0wc-image.image) | | | | | \ |**参数** |**数据类型** |**是否必选** |**描述** | |---|---|---|---| | | | | | \ |**feedback** |Object |可选 |用于配置用户对智能体的回答进行评价（点赞 / 点踩）。 | | | | | | \ |**feedback.isNeedFeedback** |Boolean |可选 |聊天界面中是否显示用户反馈（点赞 / 点踩）按钮。 |\ | | | | |\ | | | |* `true`：显示反馈按钮，用户可对智能体的回答进行评价。 |\ | | | |* `false`：（默认值）隐藏反馈按钮，禁用评价功能。 | | | | | | \ |**feedback.feedbackPanel** |Object |可选 |配置当用户反馈不满意时，显示的反馈卡片的内容。 |\ | | | |仅当 `isNeedFeedback` 为 `true` 时生效。 | | | | | | \ |**feedback.feedbackPanel.title** |String |可选 |反馈卡片顶部的引导文本，用于解释反馈目的，例如：`您对这个回答有什么看法？请告诉我们`。 | | | | | | \ |**feedback.feedbackPanel.placeholder** |String |可选 |反馈输入框内的占位文本，提示用户输入内容例如：`请详细描述您的问题...`。 | | | | | | \ |**feedback.feedbackPanel.tags** |Array |可选 |预设的反馈标签列表，用户可快速选择问题类型。 |\ | | | |最多添加 10 个标签。一个标签中最多包含 30 个字符。 | | | | | | \ |**feedback.feedbackPanel.tags.label** |String |可选 |标签的文本内容，例如：`内容有误`、`不够详细`等。 | | | | | | \ |**feedback.feedbackPanel.tags.isNeedDetail** |Boolean |可选 |设置当用户选择此标签后，是否强制要求其填写详细描述。 |\ | | | | |\ | | | |* `true`：用户选择标签后必须填写详细反馈才能提交，对于需要更多上下文的问题，例如`其他`标签，建议设为 `true`。 |\ | | | |* `false`：（默认值）用户可仅选择标签不填写详情。 | 示例代码如下： ```TypeScript ui: { chatBot: { feedback: { isNeedFeedback: true, feedbackPanel: { title: '您对这个回答有什么看法？请告诉我们', placeholder: '请详细描述您的问题...', tags: [ { label: '信息不正确' }, { label: '涉及敏感信息', isNeedDetail: true } ] } } } } ``` ### 会话列表 {#9b803e65} `ui.conversations` 参数用于控制是否展示会话列表功能。开启后，聊天框左上角会新增一个会话列表按钮，用户可借此查看历史对话、重新发起对话、创建新的会话、重命名或删除会话，实现便捷的会话管理。 ::::cols @col 50 ![Image=250x412](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/b2d13c6bd7454490a851d3443e8785e9~tplv-goo7wpa0wc-image.image) @col 50 ![Image=250x333](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/faf17b890b0e45ed886e2d2390d0f36b~tplv-goo7wpa0wc-image.image) :::: | | | | | \ |**参数** |**数据类型** |**是否必选** |**描述** | |---|---|---|---| | | | | | \ |isNeed |boolean |可选 |\ | | | |是否展示会话列表功能。 |\ | | | | |\ | | | |* true：展示会话列表功能。 |\ | | | |* false：（默认）不展示会话列表功能。 | 示例代码如下： ```TypeScript 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 } } ``` ## 相关操作 {#64b1859c} ### 更新 SDK 版本 {#9fdedfb4} 扣子 Chat SDK 将持续更新迭代，支持丰富的对话能力和展示效果。你可以在 Chat SDK 的 script 标签中指定 Chat SDK 的最新版本号，体验和使用最新的 Chat SDK 对话效果。 在以下代码中，将 ***++{{version}} ++​***部分替换为 Chat SDK 的最新版本号。你可以在[Chat SDK 发布历史](/developer_guides/web_sdk_changelog)中查看最新版本号。 :::: tabs @tab 智能体 ```HTML ``` @tab 扣子应用 ```HTML ``` :::: ### 解绑 Chat SDK {#7e924b78} 如果不再需要通过 Chat SDK 使用 AI 应用，可以在发布页面点击**解绑**按钮。一旦**解绑**，智能体或应用就无法通过集成的 Web 应用程序使用。 如果您想恢复 Web 应用程序的访问，需要再次将智能体或应用发布为 Chat SDK。 :::: tabs @tab 智能体 ![Image=748x150](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/1b4e9e9a9776459aa2b8a344f33f2ac9~tplv-goo7wpa0wc-image.image) @tab 应用 ![Image=504x196](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/5a9649586acb426791a14f2e72eed588~tplv-goo7wpa0wc-image.image) :::: ## 完整示例代码 {#94325683} 以下是一段完整的 Chat SDK 调用智能体的代码示例。 ```HTML

Hello World

``` ## 相关文档 {#9dec98a8} 如果需要将不同业务侧用户的会话互相隔离开来，每个用户只能看到自己和智能体的对话历史，请参见[如何实现会话隔离](/developer_guides/session_isolation)。