二关节机械臂PD阻抗控制MATLAB仿真与参数整定
2026/8/31 8:52:23
Dograh嵌入（Embed）功能教程：把语音AI聊天/通话组件嵌入你的网站
【免费下载链接】dograhOpen source voice AI platform. Self-hosted alternative to Vapi and Retell. On Prem, BYOK across Speech to Speech or LLM/STT/TTS, with a visual workflow builder, MCP native and telephony support.项目地址: https://gitcode.com/GitHub_Trending/do/dograh
Dograh 是一个开源语音 AI 平台（Vapi / Retell 的自托管替代方案），它的Embed（嵌入）功能让你只需复制一段<script>代码，就能把语音 AI 通话组件或聊天组件嵌入到你自己的网站中——访客无需登录你的后台，即可直接开口说话或用文字与你的语音 AI 智能体互动。本教程面向新手，完整讲解如何配置 Widget、三种嵌入模式的区别，以及进阶的访客上下文传递技巧。
🚀 快速上手：4 步生成嵌入代码
整个流程都在 Dograh 控制台的Agent 设置 → Add to Website中完成，不需要写后端代码。
第 1 步：打开你的 Agent 编辑器，点击右上角齿轮图标进入设置。
第 2 步：向下滚动到Add to Website区域，点击Configure Widget按钮。
第 3 步：在弹出的 Widget 配置对话框中：
- 开启Embedding；
- 在Allowed Domains中填入你网站的域名（留空则允许所有域名，测试时记得加上
localhost）； - 选择Widget Type：
Voice（语音通话）或Chat（文字聊天）； - 选择Embed Mode：
Floating Widget/Inline Component/Headless； - 按需定制按钮位置、颜色、文案，点击Save Configurations。
第 4 步：复制自动生成的嵌入代码，粘贴到你网页的<head>或<body>中即可上线。
生成的代码本质上是一个异步加载dograh-widget.js的<script>标签，其中js.src携带了你的embed token（形如emb_...，由 api/db/embed_token_client.py 用密码学安全随机数生成）。服务端脚本本体见 ui/public/embed/dograh-widget.js，配置对话框的前端实现在 ui/src/app/workflow/[workflowId]/components/EmbedDialog.tsx。
🎙️ 两种 Widget 类型：语音通话 vs 文字聊天
| 类型 | 访客如何互动 | 适用场景 |
|---|---|---|
| Voice | 通过 WebRTC 实时音频通话，需要麦克风 | 客服咨询、语音助手 |
| Chat | 在聊天面板中输入文字，AI 以文字回复 | 帮助中心、轻量问答 |
聊天模式的一些行为值得注意：
- 访客点击聊天按钮时才开始对话，Agent 会先打招呼；
- 一个聊天会话最长持续1 小时，过期后出现 “Start new chat” 按钮；
- 刷新页面会开启新会话；
- 每次会话计入该 embed token 的使用次数，并与语音通话一样记录在 Agent 的通话历史中，可查看完整文字稿。
🧩 三种嵌入模式：总有一种适合你的网站
| 模式 | 渲染效果 | 适合场景 |
|---|---|---|
| Floating Widget | 页面角落的胶囊形按钮 | 开箱即用，不打扰原有布局 |
| Inline Component | 渲染到你指定的<div>容器内 | 放在落地页 Hero 区、支持页 Tab 等固定位置 |
| Headless | 不渲染任何 UI，只提供window.DograhWidgetJavaScript API | 完全自定义 UI 与设计系统 |
① Floating Widget（浮动按钮）
- 语音：点击按钮开始通话，按钮文案随生命周期自动变化（“Connecting…” → “End Call” → “Retry”）；
- 聊天：点击按钮在角落打开聊天面板，关闭面板不会结束会话；
- 主页面不需要写任何 JavaScript，粘贴嵌入代码就是全部集成工作。
② Inline Component（内联组件）
在希望出现组件的位置放一个容器即可，Widget 会自动挂载：
<!-- 先粘贴 Dograh 嵌入代码，再放这个容器 --> <div id="dograh-inline-container"></div>在 React 中则通过window.DograhWidget.initInline({ container })初始化（React 挂载可能晚于脚本加载，官方文档给出了轮询等待的完整示例）。
③ Headless（无界面模式）
组件不提供任何 UI，你自己画按钮、面板，通过 JavaScript API 驱动 Agent，核心方法包括：
- 语音：
start()/end()/onStatusChange()/onError()； - 聊天：
startChat()/sendMessage(text)/onMessage()/onChatStateChange()。
⚠️ 注意：start()必须在真实用户手势（如 click）中调用，否则浏览器会拒绝授权麦克风。
🧠 进阶：给语音AI传递访客上下文
你的页面通常已经知道访客信息——姓名、套餐、购物车金额。通过data-dograh-context属性（生成代码里已预置page_url和today两个字段）把任何页面数据传给 Agent，即可在任意节点提示词中用模板变量引用：
Greet {{initial_context.customer_name | there}} and mention their {{initial_context.plan}} plan.页面加载后才获得的信息（SPA 中登录、切换路由等），调用以下方法即可，后续会话自动合并：
window.DograhWidget.setContext({ customer_name: user.firstName, plan: user.plan });🔒安全提醒：上下文来自访客浏览器，可被读取和篡改。切勿传递密钥，也不要用它作为权限判断的依据；需要可信数据时，传一个
customer_id，让 Agent 通过 Pre-Call Data Fetch 从你的 API 拉取真实详情。
✅ 上线前检查清单
- HTTPS 要求：语音 Widget 的页面必须用 HTTPS 或
localhost服务，否则浏览器拒绝麦克风权限； - Allowed Domains：若设置了域名白名单，测试环境（如
localhost）也要加进去，否则请求会被 403 拒绝； - 回调时机：Widget 脚本是异步加载的，注册
on*回调要等window.DograhWidget可用后再执行； - Token 管理：每个 Workflow 只能有一个激活的 embed token，支持设置使用次数上限和过期时间（默认 30 天），相关端点见 api/routes/workflow_embed.py；
- 公开接口安全：嵌入组件走的是免登录的公开接口
/public/embed，内置 Origin 域名校验与 CORS 控制，实现见 api/routes/public_embed.py 和 api/routes/public_embed_chat.py。
📖 参考资料
| 资料 | 路径 |
|---|---|
| 官方嵌入文档（含 React / Vanilla JS 完整示例） | docs/voice-agent/add-to-website.mdx |
| Widget 嵌入配置界面源码 | ui/src/app/workflow/[workflowId]/components/EmbedDialog.tsx |
| 嵌入 Token 与使用量管理 | api/db/embed_token_client.py |
| 通话记录查看 | docs/images/conversation-history.png 所在文档 |
照着上面的步骤，十分钟以内你就能把 Dograh 语音 AI 聊天/通话组件嵌入到任何网站。更多节点级配置（提示词、工具、知识库）可参考 docs/voice-agent/ 下的官方文档。
【免费下载链接】dograhOpen source voice AI platform. Self-hosted alternative to Vapi and Retell. On Prem, BYOK across Speech to Speech or LLM/STT/TTS, with a visual workflow builder, MCP native and telephony support.项目地址: https://gitcode.com/GitHub_Trending/do/dograh
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考