在你的网页中嵌入 Coze 智能客服：一步步打造专属 AI Agent

引言

在 AI 浪潮席卷各行各业的今天，智能客服早已不再是"高大上"的专属。借助 Coze（扣子）平台，我们每个人都能轻松创建一个属于自己的 AI 客服机器人，并将其无缝集成到任意网页中------无论你是教育产品开发者、SaaS 创业者，还是个人站长。

本文将手把手带你完成这一过程，从知识库构建、Bot 发布，到前端代码调用，尤其会对 main.js 文件进行逐行详细注释，确保你不仅"会用"，更"懂原理"。

一、为什么选择 Coze？

Coze 是字节跳动推出的 AI Agent 智能办公平台，其核心优势在于：

RAG（检索增强生成）技术：让大模型基于你提供的私有知识库回答问题，避免"胡说八道"。
低代码发布 API：无需搭建后端，一键生成可调用的 Bot 接口。
多场景适配：无论是课程咨询、编程答疑，还是法律/医疗知识问答，只需"喂"对资料。

💡 举个例子：你想做一个"Python 编程课"的客服机器人。学生问："第3章作业怎么提交？"------只要你在知识库里写清楚流程，AI 就能精准回答，而不是瞎猜。

二、准备工作：创建并发布你的 Coze Bot

登录 Coze 平台
新建 Bot，配置如下：
- 添加 课程知识库（如 PDF、Markdown、网页链接等）
- 启用 RAG 检索，确保回答基于你的资料
- 测试对话效果，调整提示词（Prompt）
发布为 API

点击「发布」→「API 调用」，你会得到两个关键信息：
- VITE_BOT_ID：你的 Bot 唯一标识（即发布 ID）
- VITE_API_KEY：调用权限密钥（Token）

智能体如图，本文重点讲述如何调用，对如何创建智能体不过多描述，可直接使用本文的示例URL

https://www.coze.cn/space/7567783700911013940/bot/7578869824248676361/publish

📌 示例 URL 中已包含 Bot ID：
https://www.coze.cn/space/7567783700911013940/bot/7578869824248676361/publish

→ 7578869824248676361 就是 VITE_BOT_ID

三、前端集成：在任意网页中调用 Coze Agent

现在，我们进入最激动人心的部分------把 AI 客服嵌入你的网站！

我们来看一个轻量级示例项目：coze-agent-demo，基于 Vite 构建。即使你不用 Vite，也可以直接在 HTML 中引入 JS 文件。

项目初始化建议

ini 复制代码

# 使用 Trae（或 Vite）快速创建项目
npm create vite@latest coze-agent-demo -- --template vanilla
cd coze-agent-demo
# 在 .env.local 中填入：
VITE_BOT_ID=7578869824248676361
VITE_API_KEY=your_coze_api_token_here

项目结构简述

如果运行时报错显示 main.js 无法读取.env.local 的内容，再创建一个文件 .env 内容如下

ini 复制代码

# Coze API环境变量
VITE_BOT_ID=demo_bot_id
VITE_API_KEY=demo_api_key

接下来我们将重点解析 main.js 的每一行代码。

四、逐行详解 `main.js`：如何与 Coze 对话？

javascript 复制代码

// 1. 从环境变量中读取 Bot ID 和 API Key
//    在 Vite 项目中，以 VITE_ 开头的变量会被自动注入到 import.meta.env
const BOT_ID = import.meta.env.VITE_BOT_ID;
const API_KEY = import.meta.env.VITE_API_KEY;

// 2. 定义 Coze API 的请求地址
//    这是 Coze 官方提供的对话接口（WebSocket 或 REST？此处为 REST）
const API_URL = 'https://api.coze.cn/open_api/v1/chat';

// 3. 获取页面中的 DOM 元素
//    - userInput: 用户输入框
//    - sendButton: 发送按钮
//    - chatBox: 聊天消息展示区域
const userInput = document.getElementById('user-input');
const sendButton = document.getElementById('send-button');
const chatBox = document.getElementById('chat-box');

// 4. 为"发送"按钮绑定点击事件
sendButton.addEventListener('click', sendMessage);

// 5. 同时监听回车键（Enter）触发发送
userInput.addEventListener('keypress', (e) => {
  if (e.key === 'Enter') {
    sendMessage();
  }
});

// 6. 核心函数：发送消息并获取 AI 回复
async function sendMessage() {
  // 6.1 获取用户输入内容，并去除首尾空格
  const message = userInput.value.trim();
  
  // 6.2 如果输入为空，直接返回（不发送）
  if (!message) return;

  // 6.3 清空输入框，提升用户体验
  userInput.value = '';

  // 6.4 在聊天框中显示用户的消息（左侧气泡）
  appendMessage('user', message);

  // 6.5 准备请求体（payload）
  //     - bot_id: 你的 Bot 唯一标识
  //     - user_id: 可用于区分不同用户（此处简化为固定值）
  //     - query: 用户的问题
  //     - stream: 是否启用流式响应（此处为 false，使用完整响应）
  const payload = {
    bot_id: BOT_ID,
    user_id: 'user123', // 实际项目中建议用真实用户ID或会话ID
    query: message,
    stream: false
  };

  // 6.6 使用 fetch 发起 POST 请求到 Coze API
  try {
    const response = await fetch(API_URL, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`, // 6.6.1 必须携带 API Key 进行身份验证
        'Content-Type': 'application/json'     // 6.6.2 声明请求体为 JSON
      },
      body: JSON.stringify(payload) // 6.6.3 将 payload 转为 JSON 字符串
    });

    // 6.7 检查响应是否成功
    if (!response.ok) {
      throw new Error(`API error: ${response.status}`);
    }

    // 6.8 解析返回的 JSON 数据
    const data = await response.json();

    // 6.9 从响应中提取 AI 的回答
    //     Coze 的响应结构中，messages 数组包含对话历史
    //     最后一条通常是 AI 的回复，且 role 为 'assistant'
    const aiMessage = data.messages.find(msg => msg.role === 'assistant')?.content || '抱歉，我无法回答这个问题。';

    // 6.10 在聊天框中显示 AI 的回复（右侧气泡）
    appendMessage('ai', aiMessage);

  } catch (error) {
    // 6.11 错误处理：网络问题、API 限流、认证失败等
    console.error('Error:', error);
    appendMessage('ai', '哎呀，出错了！请稍后再试~');
  }
}

// 7. 辅助函数：向聊天框追加消息
function appendMessage(sender, text) {
  // 7.1 创建一个新的消息 div 元素
  const messageElement = document.createElement('div');
  
  // 7.2 根据发送者设置 CSS 类名（用于样式区分）
  messageElement.classList.add('message', sender);
  
  // 7.3 设置消息内容（注意：这里未做 XSS 防护，生产环境需转义）
  messageElement.textContent = text;
  
  // 7.4 将消息元素添加到聊天容器末尾
  chatBox.appendChild(messageElement);
  
  // 7.5 自动滚动到底部，确保最新消息可见
  chatBox.scrollTop = chatBox.scrollHeight;
}

五、关键细节解析

安全提醒

VITE_API_KEY 绝不能暴露在前端生产环境 ！
当前 demo 仅适用于本地开发或演示。
正确做法 ：通过你自己的后端代理请求，由后端持有 API_KEY，前端只与你的服务器通信。

RAG 如何生效？

当你在 Coze 后台上传了课程文档，Coze 会自动将其向量化。当用户提问时：

系统先在知识库中检索相关片段
将片段 + 用户问题一起送入 LLM
LLM 基于上下文生成准确回答

✅ 这就是为什么"喂饭"知识库比单纯依赖模型更重要！

样式与交互

index.html 代码内容

xml 复制代码

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Coze API Demo</title>
</head>
<body>
  <h1>Coze API DEMO 随处智能</h1>
  <input type="text" id="ipt" placeholder="请输入问题">
  <div id="reply">think...</div>
  <script type="module" src="./src/main.js"></script>
</body>
</html>

运行该文件后，在浏览器页面右键点击检查，打开控制台，输入问题并将焦点移出输入框，控制台将显示内容

当网页从

转变为

即为运行成功

六、扩展可能

支持图片上传：Coze API 支持多模态输入，可让学生拍照提问编程题。
会话记忆 ：通过维护 conversation_id 实现上下文连续对话。
虚拟数字人：结合语音合成（TTS）与动画，打造拟人化客服。

结语

通过 Coze，我们不再需要从零训练模型，而是聚焦于知识的组织与交付。正如那句老话："授人以鱼不如授人以渔"------而 Coze 让你既能"给鱼"，又能"教钓鱼"。

现在，打开你的编辑器，把那个沉睡的知识库唤醒，让它变成一个 7×24 小时在线的智能助手吧！

🌟 你的知识，值得被 AI 更好地讲述。

Happy Coding！🤖✨