Skip to content

8. Chat SDK

Jump to bottom
newacc edited this page Aug 29, 2025 · 2 revisions

本文档基于 Coze Studio 当前最新版本撰写，你可以根据版本更新特性按需升级使用 Chat SDK。Coze Studio 发布历史可参考 GitHub Releases。

准备工作

调试 Chat SDK

  1. 启动后端服务。

  2. 修改配置文件。 进入 frontend/packages/studio/open-platform/chat-app-sdk 目录，修改 .env.default 文件名为 .env.local，并填入以下信息：

    • 智能体发布 Chat SDK：
      • CHAT_APP_INDEX_COZE_BOT_ID：智能体的 ID。在智能体编排页面的 URL 中，查看 bot 关键词之后的字符串就是智能体 ID。例如https://www.coze.cn/space/341****/bot/73428668*****，智能体 ID 为 73428668*****。
      • CHAT_APP_COZE_TOKEN：准备工作中获取的 Personal Access Tokens。
    • 对话流发布 Chat SDK：
      • CHAT_APP_CHATFLOW_COZE_APP_ID：扣子应用的 ID。 在扣子应用中打开工作流或对话流，URL 中 project-ide 参数之后的字符串就是 appId。
      • CHAT_APP_CHATFLOW_COZE_WORKFLOW_ID：工作流或对话流的 ID。 在扣子应用中打开工作流或对话流，URL 中 workflow 参数之后的字符串就是 workflowId。
      • CHAT_APP_COZE_TOKEN：准备工作中获取的 Personal Access Tokens。

  3. 执行以下命令启动 ChatSDK 前端。 在frontend/packages/studio/open-platform/chat-app-sdk 目录下执行以下命令：

    npm run dev

  4. 调试 Chat SDK。 浏览器打开 http://localhost:8081/client 开始调试。

发布 Chat SDK

  1. 修改 Chat SDK 接口域名。 打开文件 frontend/packages/studio/open-platform/open-env-adapter/src/chat/index.ts，并将 openApiHostByRegion 修改为你的后端接口域名。

  2. 构建镜像。 进入 frontend/packages/studio/open-platform/chat-app-sdk 目录，执行以下命令：

    npm run build

  3. 上传 CDN 资源。 镜像构建完毕后，会自动生成 libs 目录。推荐将 libs 目录下的所有资源上传至自己的 CDN 服务器。 你也可以通过 npm 方式上传：

    1. 修改package.json中的包名和版本号为你自己的报名和版本号。
    2. 执行 npm publish，即可通过 https://cdn.jsdelivr.net/npm/包名@版本号/libs/cn/index.js访问资源。

安装 ChatSDK

  1. 安装 ChatSDK。 你可以直接在页面中通过 script 标签的形式加载 Chat SDK 的 js 代码。注意替换包名和版本号。
<script src="https://cdn.jsdelivr.net/npm/包名@版本号/libs/cn/index.js"></script>
  1. SDK安装成功后，在代码中配置以下参数： 具体可配置的参数可前往商业版本 配置参数 文档与 WebChatClient 入参对比查看。需要注意的是，Coze Studio 开源版 Chat SDK 暂不支持商业版本中的部分功能，例如语音播放、语音录制、语音通话等。 代码示例如下： 
    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.isIframe - Whether to use the iframe method to open the chat box
  * @param config.appInfo.appId - AI app ID.
  * @param config.appInfo.workflowId - Workflow or chatflow ID.
  */
  config: {
    type: 'bot',
    bot_id: 'xxxx',
    isIframe: false,
  },
  /**
  * 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: 'xxxx',
    onRefreshToken: async () => 'token'
  },
  /**
  * 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/eden-cn/lm-lgvj/ljhwZthlaukjlkulzlp/coze/coze-logo.png',
    nickname: 'User',
  },
  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/eden-cn/lm-lgvj/ljhwZthlaukjlkulzlp/coze/chatsdk-logo.png',
      layout: 'pc',
      lang: 'en',
      zIndex: 1000
    },
    /**
    * Controls whether to display the top title bar and the close button
    * @param header.isShow - Whether to display the top title bar.
    * @param header.isNeedClose - Whether to display the close button.
    */
    header: {
      isShow: true,
      isNeedClose: true,
    },
    /**
    * 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: 'Powered by ...',
    },
    /**
    * 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: 'Coze Bot',
      uploadable: true,
      width: 390,
    },
  },
});

Home

Clone this wiki locally