嵌入带 lead capture 的知识库聊天 widget

把你的文档变成门口的助手

你的知识库已经包含访客在寻找的答案。嵌入的聊天 widget 把这些答案带到你的网站，成为一扇对话式入口：访客提问，widget 运行你的内部团队使用的同一条混合 RAG 管线和 agent 基础设施，回答带着来自你选择开放的 workspace 的引用到达。本教程走遍 widget 的嵌入、对它回答内容的控制、lead 捕获和正确的 CORS 配置--从管理面板到几分钟内可用的代码片段。

两步 embed：loader 与沙箱 iframe

widget 围绕安全导向的 embed 模式构建。它不把 markup 和样式注入你的页面，而是分两步到达：

1. Loader 脚本。 在网站上添加一个 script 标签，指向你的 widget 服务并带上 widget ID。loader 是一个小型 JavaScript 文件，在宿主页面中创建一个 iframe。
2. iframe 面板。 iframe 加载一个独立的 Preact 应用--以 IIFE bundle 编译、CSS 内联--在它自己的文档内绘制浮动按钮、聊天面板和所有交互。

<script src="https://your-simmetric-chat.com/widget/loader.js?widgetId=WIDGET_ID"></script>

为什么要 iframe？因为把不可信内容的字符串插值进宿主页面正是经典的 XSS 路径。让 widget 界面运行在不透明来源的沙箱 iframe 中，彻底消除了这一类风险：聊天内容永远不会在你的页面上下文中执行。旧的字符串插值 embed 路径正是因此从产品中移除，所以两步模式不是众多选项之一--它就是 embed。

iframe 与页面之间的通信通过一个小型版本化 postMessage 协议（消息类型 simmetric:*），处理 FAB 开合、FAB 重新着色和会话存储握手。双方都会针对各自期望的精确 contentWindow 校验每条入站消息，因此不同 iframe 之间伪造的消息会被忽略。

创建 widget 并指向知识

一切从管理面板开始：

1. 从 设置 → Widgets 创建一个 widget。创建受许可证约束（widget_enabled），并遵守套餐的 widget 数量上限。
2. 把 widget 关联到一个或多个 workspace。workspace 白名单原子替换所有先前的关联，因此对知识库访问分层就是选择附加哪些 workspace 的问题。
3. 配置 branding：主色、机器人名称、logo、位置（右下或左下）。Community 层级部署在字段为空时获得合理的默认值；完整定制和 white-labeling 是 enterprise flag。
4. 把 embed 代码片段复制到你的网站 HTML 中。

由于 widget 按 workspace 定义，widget 可汲取的知识恰好是关联 workspace 的知识库之并集--不多不少。支持 widget 可以看到公开文档 workspace，却永远不触碰内部项目数据。

回答的 model pin：服务端解析

最近的一项新增对质量控制很重要：每个 widget 的配置可以选择为该 widget 聊天回答服务的特定 LLM provider 和模型。pin 保存在 widget 行上，在每次聊天请求时于服务端解析--永远不由客户端、widget 代理或访客浏览器提供。被 pin 的模型优先于 workspace 默认值，没有 pin 的 widget 保持标准解析链。实际效果：你的营销 widget 可以运行在你为公开回答验证过的那一个模型上，无论任何人在客户端侧如何篡改。

尊重访客的 lead 捕获

widget 的 lead 捕获是为公开表单的现实设计的：滥用集中在收集数据的地方，因此 lead 端点被刻意限制为每来源每小时 3 次请求（限制对用户可见）。流程：

• 访客在聊天前看到个人信息同意门槛--对数据如何被处理的明确告知，而不是藏在底部的政策链接。
• lead 卡片在对话中或对话后收集联系方式，提交进入管理面板中 widget 的 lead 收件箱，并支持 CSV 导出接入你的管线。
• 会话按设计是匿名的：服务器创建带 256 位 token、24 小时过期的会话，后续每个请求都对它校验。每会话限制（每小时 20 条消息、每天 5 段对话）超限时返回 429 并带 retryAfter 提示，界面显示速率限制警告而不是静默失败。

速率限制是信任故事的一部分，不是事后补丁：公开聊天表面应当在负载或滥用下优雅降级，而 lead 限制器是 widget 侧三个限制器中最严的一个。

CORS：设计上默认关闭

widget 流量按定义跨来源，因此 CORS 是安全表面的一部分，而不是事后补丁。每个 widget 携带自己的 allowedOrigins 列表，可在管理面板编辑。运行时，动态 CORS 中间件针对该 widget 的列表校验每个请求的 Origin 头--不允许来源的请求在 preflight 阶段被拒绝，并且中间件失败关闭：如果来源检查无法访问数据库，访问被拒绝而不是放行。

一次配置完成：

• 把你网站的来源（协议和主机，不要在结尾斜杠上玩花样）添加到 widget 的允许来源。
• 记住子域变体算作不同来源--example.com 和 www.example.com 是两条记录。
• 生产环境使用 https:// 来源；widget 服务遵循与栈其余部分相同的 URL 规则。

其他一切--loader URL、iframe、会话引导、SSE 聊天流--都使用你部署 widget 服务的同一主机，因此来源信任只在唯一一处决定：widget 的允许列表。

什么在哪里运行

快速方位图，因为 widget 触及三个进程：

• 主服务器--widget 的 CRUD 与 branding、workspace 关联、widget 服务用其 API key 调用的内部 API，以及面向管理员的 lead/analytics 端点。widget 功能关闭时，整个内部路由返回 402。
• widget 服务--公开 embed 表面：JS loader、iframe HTML、会话创建、缓存配置下发、到主服务器的聊天 SSE 代理和 lead 端点。它用 WIDGET_API_KEY 向主服务器认证，并自带速率限制器。
• iframe--IIFE Preact 客户端与聊天生命周期：会话创建、逐 token SSE 流式输出、引用展示、建议问题和同意门槛。

聊天代理转发的内部流式 API 事件格式完全一致--状态消息、计划公告、流式 token、引用和终止事件 done/error--因此你团队在工作区聊天里看到的一切，访客都会在 widget 里体验到。

上线清单

• widget 已创建、许可证功能已启用、workspace 已关联
• branding 已设置；若 widget 不应带产品品牌则开启 white-label flag
• 回答 model pin 已在 widget 行上设置（服务端解析）
• 允许来源覆盖将嵌入它的每个站点和子域
• lead capture 端到端验证：同意门槛、提交、管理收件箱、CSV 导出
• 理解速率限制：每小时 3 个 lead、每会话每小时 20 条消息、每天 5 段对话

从那里开始，widget 就是 drop-in：一个 script 标签、一份允许列表、一个你已经信任的知识库。当访客提问时，他们得到的回答恰好以你选择的 workspace 为根据--还有一条对人类礼貌、对机器人严厉的 lead 捕获管线。

在文档中阅读完整指南 →