助手
扣子 AI 帮助与支持
你好,我是 扣子 文档问答助手 🎉 你在阅读当前文档的过程中,无论对文档概念的解释,还是文档内容方面的疑问,都可以随时向我提问,我会全力为你解答
推荐问题
如何快速了解这个空间的核心内容?
有哪些近期更新的重点文档?
我应该从哪些文档开始阅读?
文档反馈
低代码项目
快速开始
智能体
工作流
应用
资源
发布
模型
多人协作
推广与变现

安装并使用 Chat SDK

更新于: 2026-06-25 19:29:14

本文介绍如何安装并使用扣子 Chat SDK,开发者可以参考本文档在自己开发的网站或 App 中快速实现智能对话功能。适用于智能客服、答疑助手或企业内部的 IT 支持机器人等场景。

前置条件

浏览器兼容性

Chat SDK 的运行环境要求如下表所示。

浏览器

版本限制

Chrome

87.0 及以上

Edge

88.0 及以上

Safari

14.0 及以上

Firefox

78.0 及以上

获取访问密钥

访问密钥用于 Chat SDK 的身份认证与鉴权。根据使用场景选择合适的鉴权方式,各鉴权方式的区别请参见鉴权方式概述

场景

推荐方案

说明

参考文档

开发调试

个人访问令牌(PAT)

快速跑通 Chat SDK 的整体流程。

添加个人访问令牌

生产环境

服务访问令牌(SAT)

操作更简单,能够有效简化授权流程,适合需要长期稳定访问且无需进行会话隔离的场景。
仅企业版(企业标准版、企业旗舰版)支持使用 SAT 鉴权。

添加服务访问令牌

OAuth 鉴权

支持渠道用户访问智能体、会话隔离(即智能体不同账号的消息内容互相隔离)。

OAuth 应用管理
OAuth JWT 授权(渠道场景)

权限要求

访问密钥需被授予以下权限,才能正常使用 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

说明

渠道 OAuth 访问密钥的权限点是渠道类型的 OAuth 应用中设置的权限点,创建应用并授权的详细说明可参考OAuth JWT 授权(渠道场景)

调试与体验 Chat SDK

你可以通过 Playground 调试与体验 Chat SDK 各配置项的功能和效果。
Image

配置流程

步骤一:发布智能体或扣子应用

在智能体或 AI 应用的发布页面,选择 Chat SDK,并单击发布。发布的详细流程可参考:

步骤二:获取安装代码

进入发布页面复制 SDK 安装代码。

  1. 在智能体的编排页面,单击发布,进入发布页面。
  2. 发布页面,单击安装
    页面将展示安装代码,安装代码中默认使用最新版本的 Chat SDK 配置。
    Image
  3. 复制此安装代码。
    Image
    请妥善保存此代码用于步骤三。
  1. 在扣子应用的编排页面右上角,单击发布下拉按钮查看指定版本的发布状态。
  2. 确认 Chat SDK 发布成功后,单击安装指引
    Image
  3. 根据页面提示复制安装代码。此代码将在后续的配置中使用。
    Image

步骤三:安装 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:(默认值)智能体。
    • 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 会将自定义参数的值传递给对话流。具体用法和示例代码可参考为自定义参数赋值

    说明

    单 Agent(对话流模式)​的智能体支持该配置。

  • auth:表示鉴权方式。当未配置此参数时表示不鉴权。为了账号安全,建议配置鉴权。

    参数

    数据类型

    是否必选

    描述

    type

    String

    必选

    可指定为 token,通过访问密钥鉴权,支持的访问密钥包括 PAT、SAT 和 OAuth 访问密钥。关于访问密钥的详细说明可参考鉴权方式概述

    token

    String

    type为 token 时必填

    typetoken 时,指定使用的访问密钥。

    • 调试场景可以直接使用个人访问令牌(PAT),快速体验 Chat SDK 的效果。
    • 正式上线时建议通过 SAT 或 OAuth 实现鉴权逻辑,并将获取的 OAuth 访问密钥填写在此处。

    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方式来打开聊天框,默认为 true

    • true:使用 iframe 方式打开聊天框。聊天框内容在独立的 iframe 窗口中运行。
    • false(推荐):聊天框直接集成到你的网页中,与网页共用一个运行环境。可以规避小程序对跨域名的限制。

    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]

    给应用中的自定义参数赋值并传给对话流。
    如果在对话流的开始节点设置了自定义输入参数,你可以通过 parameters 参数指定自定义参数的名称和值,ChatSDK 会将自定义参数的值传递给对话流。具体用法和示例代码可参考为自定义参数赋值

  • auth:表示鉴权方式。当未配置此参数时表示不鉴权。为了账号安全,建议配置鉴权。

    参数

    数据类型

    是否必选

    描述

    type

    String

    必选

    可指定为 token,通过访问密钥鉴权,支持的访问密钥包括 PAT、SAT 和 OAuth 访问密钥。关于访问密钥的详细说明可参考鉴权方式概述

    token

    String

    type为 token 时必填

    typetoken 时,指定使用的访问密钥。

    • 调试场景可以直接使用个人访问令牌(PAT),快速体验 Chat SDK 的效果。
    • 正式上线时建议通过 SAT 或 OAuth 实现鉴权逻辑,并将获取的 OAuth 访问密钥填写在此处。

    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 配置

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 传递给扣子服务端。
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 的对话记录。详细说明可参考消息日志

配置示例如下:

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 配置

ui.base 参数用于添加聊天窗口的整体 UI 效果,包括应用图标、页面布局、语言属性等。

参数

数据类型

是否必选

示例

描述

icon

String

可选

https://example.com/obj/coze-web-cn/obric/coze/favicon.1970.png

应用图标,必须是一个可访问的公开 URL 地址。如果不设置,则使用默认扣子图标。

说明

扣子企业旗舰版支持将 icon 修改为自定义的品牌 Logo,扣子团队版和个人版不支持自定义品牌。

layout

String

可选

pc

聊天框窗口的布局风格,支持设置为:

  • mobile:移动端风格,聊天框窗口铺满移动设备全屏。
  • pc:PC 端风格,聊天框窗口位于页面右下角。

未设置此参数时,系统会自动识别设备,设置相应的布局风格。

lang

String

可选

zh-CN

系统语言,例如工具提示信息的语言。

  • en:(默认)英语。
  • 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 参数用于控制是否在页面右下角展示悬浮球。默认展示,用户点击悬浮球后将弹出聊天窗口。
Image

参数

数据类型

是否必选

示例

描述

isNeed

Boolean

可选

true

是否在页面右下角展示悬浮球。

  • true:(默认)展示悬浮球。
  • false:隐藏悬浮球。若设置为隐藏悬浮球,开发者需要通过以下方法控制聊天框的展示或隐藏效果。具体请参考下文的示例代码。
    • 显示聊天框:​cozeWebSDK.showChatBot()
    • 隐藏聊天框:​cozeWebSDK.hideChatBot()

示例代码如下:

// 在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 参数隐藏此文案或改为其他文案,支持在文案中设置超链接。
底部文案默认展示效果如下:
Image
footer 参数配置说明如下:

参数

数据类型

是否必选

示例

描述

isShow

Boolean

可选

true

是否展示底部文案模块。

  • true:展示。此时需要通过 expressionTextlinkvars 参数设置具体文案和超链接。
  • 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 href="https://www.test1.com">A</a> <a href="https://www.test2.com">B</a>

配置示例如下:

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

顶部标题栏配置

聊天框顶部默认展示智能体名称、icon 及关闭按钮。展示效果类似如下:
Image
您可以通过 ui.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: '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

可选

电商客服

聊天框的标题,若未配置,使用默认名称 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

isNeedFunctionCallMessage

Boolean

可选

true

设置是否在聊天框中显示插件工具调用的信息。

  • true:(默认值)聊天框中将显示调用的插件工具。
  • false:聊天框中不显示插件工具调用的信息。

isNeedAddNewConversation

Boolean

可选

true

设置是否在聊天框中显示创建新会话功能。

  • true:聊天框右上角将显示创建新会话按钮,单击后即可创建新的会话。
  • false:(默认值)聊天框右上角不显示创建新会话按钮。

Image

isNeedQuote

Boolean

可选

true

设置是否支持对智能体或应用回复的消息进行追问。

  • true:支持对消息进行追问。
  • false:(默认值)不支持追问功能。

Image

说明

仅支持对返回的文本和图片消息进行追问,不支持对卡片和文件进行追问。

相关回调:

  • onHide:​当聊天框隐藏的时候,会回调该方法。
  • onShow: 当聊天框显示的时候,会回调该方法。
  • onBeforeShow: 聊天框显示前调用,如果返回了 false,则不会显示。支持异步函数。
  • onBeforeHide: 聊天框隐藏前调用,如果返回了 false,则不会隐藏。支持异步函数。

在以下示例中,聊天框标题为 Kids’ Playmate | Snowy,并开启上传文件功能。
Image
对应的代码示例如下:

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 参数中配置是否允许用户对智能体的回答进行评价(点赞 / 点踩),默认禁用评价功能。
Image

参数

数据类型

是否必选

描述

feedback

Object

可选

用于配置用户对智能体的回答进行评价(点赞 / 点踩)。

feedback.isNeedFeedback

Boolean

可选

聊天界面中是否显示用户反馈(点赞 / 点踩)按钮。

  • true:显示反馈按钮,用户可对智能体的回答进行评价。
  • false:(默认值)隐藏反馈按钮,禁用评价功能。

feedback.feedbackPanel

Object

可选

配置当用户反馈不满意时,显示的反馈卡片的内容。
仅当 isNeedFeedbacktrue 时生效。

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:(默认值)用户可仅选择标签不填写详情。

示例代码如下:

ui: {
  chatBot: {
    feedback: {
      isNeedFeedback: true,
      feedbackPanel: {
        title: '您对这个回答有什么看法?请告诉我们',
        placeholder: '请详细描述您的问题...',
        tags: [
          {
            label: '信息不正确'
          },
          {
            label: '涉及敏感信息',
            isNeedDetail: true
          }
        ]
      }
    }
  }
}

会话列表

ui.conversations 参数用于控制是否展示会话列表功能。开启后,聊天框左上角会新增一个会话列表按钮,用户可借此查看历史对话、重新发起对话、创建新的会话、重命名或删除会话,实现便捷的会话管理。

Image

Image

参数

数据类型

是否必选

描述

isNeed

boolean

可选

是否展示会话列表功能。

  • true:展示会话列表功能。
  • false:(默认)不展示会话列表功能。

示例代码如下:

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  
  }
}

相关操作

更新 SDK 版本

扣子 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

如果不再需要通过 Chat SDK 使用 AI 应用,可以在发布页面点击解绑按钮。一旦解绑,智能体或应用就无法通过集成的 Web 应用程序使用。 如果您想恢复 Web 应用程序的访问,需要再次将智能体或应用发布为 Chat SDK。

Image

Image

完整示例代码

以下是一段完整的 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>

相关文档

如果需要将不同业务侧用户的会话互相隔离开来,每个用户只能看到自己和智能体的对话历史,请参见如何实现会话隔离