网站 / H5 嵌入
异域网站优先使用渠道生成的现有网页组件。
下载接入包
- Web / H5
含原版渠道 iframe 示例及无 UI 客户端。复用完整渠道外观请选择 web/voice-example.html 或渠道嵌入代码;无 UI 客户端需自行绘制界面。
接入步骤
- 在自建渠道创建入口,绑定已发布智能体,并在“皮肤与代码”选择网页聊天框。
- 配置允许嵌入的网站域名,复制该入口生成的 widget.js / iframe 代码。保留生成的 key 与 entryId,不手改为其他企业入口。
- 将生成代码放到自己的站点,设置由“聊一聊”触发打开;检查首次访问不会自动展开或开始语音。
- 在桌面和手机分别检验展开、收起、键盘和关闭,并验证真实 AI / 人工收发。
嵌入与无 UI SDK
外站使用网页嵌入;同源 HTTPS 才使用下一篇的无 UI 客户端。不要仅为了跨域放开全部 API CORS。自定义 UI 不继承现有网页的所有功能,需要自己处理状态与错误。
H5 完整语音接入
接入包 0.3.0 的 web/voice-embed.mjs 与 voice-example.html 提供完整渠道界面和现有语音引擎;无 UI 消息 SDK 不提供音频。只在用户点击打开后创建 iframe,在渠道内点击开始才申请录音。
父子页面均需 HTTPS;iframe 只委派精确客服 origin 的 microphone/autoplay。父站点 Permissions-Policy、CSP 与渠道允许来源仍须匹配;allow 属性不能突破响应头限制。嵌套 iframe 每层都需委派,勿放开全域 CORS。
新 helper 在关闭、pagehide 或父页面隐藏时停止并移除 iframe;回前台需要再次打开,不自动开麦。停止消息检查父窗口、精确来源、公开 key 和入口;账号退出 destroy 后换 UUID。现有 widget 折叠行为不改。
来源限制
线上主机、协议和允许来源需一致。原生容器可能没有 Referer,应使用专用渠道评估公开入口策略;不能为 App 接入删除原网站的来源限制,也不能伪造 Referer。
完整 H5 语音页面示例
运行前
web/voice-example.html · 完整网页文件 · 接入包 0.3.15
- 从 Web 包保留 voice-embed.mjs 和根目录 hosted-url.mjs 的相对位置。
- 替换公开参数,通过 HTTPS 打开;父站点允许客服 origin 的麦克风和 iframe。
完整代码 · 20 行
<!doctype html>
<html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover"><title>云蝠语音客服接入示例</title>
<style>body{margin:20px;font:15px system-ui;color:#24334d;background:#f6f8fc}main{max-width:760px;margin:auto}button{padding:10px 16px;margin:0 8px 12px 0}#support{height:75dvh;min-height:360px;background:white;border-radius:14px;overflow:hidden}#status{line-height:1.6}</style></head>
<body><main><h1>在线客服</h1><p>打开后可选择文字或语音咨询,开始语音时才申请麦克风。</p><button id="open">打开客服</button><button id="close">关闭客服(结束语音)</button><p id="status" role="status"></p><div id="support"></div></main>
<script type="module">
import { createHostedVoiceEmbed } from './voice-embed.mjs';
let support;
document.querySelector('#open').onclick = () => {
try {
support ||= createHostedVoiceEmbed({
container: document.querySelector('#support'), origin: 'https://YOUR_CUSTOMER_SERVICE_ORIGIN',
key: 'YOUR_PUBLIC_KEY', entryId: 'YOUR_ENTRY_ID', clientSession: crypto.randomUUID(),
});
support.open();
document.querySelector('#status').textContent = '语音需要企业及入口已启用;授权成功后仍需核对实际 AI 回复。';
} catch (error) { document.querySelector('#status').textContent = error.message === 'VOICE_REQUIRES_HTTPS' ? '请通过 HTTPS 站点打开此示例。' : '请先填写有效的客服服务地址和入口参数。'; }
};
document.querySelector('#close').onclick = () => support?.close();
// The host must call support.destroy() before logout/account change, then create a new UUID.
</script></body></html>使用流程预览 · 示意图
帮助理解此示例的使用顺序,不执行代码或验证连接。
- 准备
从 Web 包保留 voice-embed.mjs 和根目录 hosted-url.mjs 的相对位置。 替换公开参数,通过 HTTPS 打开;父站点允许客服 origin 的麦克风和 iframe。
- 在项目中使用
web/voice-example.html · 完整网页文件
- 核对结果
点击打开仅显示渠道界面,在渠道内点击开始才申请录音;关闭或切后台结束语音。
预期结果:点击打开仅显示渠道界面,在渠道内点击开始才申请录音;关闭或切后台结束语音。
官方原始接入文档
先按云蝠指南完成入口、智能体和服务配置,再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力,不代表云蝠已开放其中全部接口;腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。
- MDN · getUserMedia 麦克风采集 ↗:核对 HTTPS、用户授权、设备和浏览器兼容性;打开页面不等于麦克风可用。
- MDN · Permissions-Policy: microphone ↗:配置父站点允许的客服来源并配合 iframe allow;响应头限制仍生效,不能用放开 CORS 解决麦克风拒绝。
实现依据 · 仓库内路径
frontend/components/channels/embed-page.tsxsdk/client-kit/README.mdsdk/client-kit/web/voice-embed.mjs
文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。