开发者文档中心

OpenAPI进入控制台

Web / H5 · 2026-10-31

网站 / H5 嵌入

异域网站优先使用渠道生成的现有网页组件。

下载接入包

接入步骤

  1. 在自建渠道创建入口,绑定已发布智能体,并在“皮肤与代码”选择网页聊天框。
  2. 配置允许嵌入的网站域名,复制该入口生成的 widget.js / iframe 代码。保留生成的 key 与 entryId,不手改为其他企业入口。
  3. 将生成代码放到自己的站点,设置由“聊一聊”触发打开;检查首次访问不会自动展开或开始语音。
  4. 在桌面和手机分别检验展开、收起、键盘和关闭,并验证真实 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 行
web/voice-example.htmlHTML
<!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>
使用流程预览 · 示意图

帮助理解此示例的使用顺序,不执行代码或验证连接。

  1. 准备

    从 Web 包保留 voice-embed.mjs 和根目录 hosted-url.mjs 的相对位置。 替换公开参数,通过 HTTPS 打开;父站点允许客服 origin 的麦克风和 iframe。

  2. 在项目中使用

    web/voice-example.html · 完整网页文件

  3. 核对结果

    点击打开仅显示渠道界面,在渠道内点击开始才申请录音;关闭或切后台结束语音。

预期结果:点击打开仅显示渠道界面,在渠道内点击开始才申请录音;关闭或切后台结束语音。

官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置,再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力,不代表云蝠已开放其中全部接口;腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

实现依据 · 仓库内路径
  • frontend/components/channels/embed-page.tsx
  • sdk/client-kit/README.md
  • sdk/client-kit/web/voice-embed.mjs

文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。