TOFFS HCS 客服聊天框集成演示

iframe 嵌入

将聊天组件以 iframe 嵌入页面。组件通过 postMessage 通知父窗口调整 iframe 尺寸，实现点击按钮展开/收起面板的效果。此方式与宿主页面完全隔离，不会产生样式冲突。

<!-- 1. 在页面中放置 iframe，指向 TOFFS HCS 聊天页面 -->
<iframe
  id="chat-iframe"
  src="https://aics.toffsdev.com/widget.html?key=wVv2zL3R8KnC7s86"
  style="
    position: fixed;
    bottom: 0;
    right: 0;
    width: 80px;
    height: 80px;
    border: none;
    z-index: 9999;
    transition: width 0.25s ease, height 0.25s ease;
  "
></iframe>

<!-- 2. 监听 postMessage 以动态调整 iframe 尺寸 -->
<script>
  window.addEventListener('message', function(e) {
    if (e.data && e.data.type === 'argus-chat-resize') {
      var iframe = document.getElementById('chat-iframe');
      iframe.style.width  = e.data.width;   // '80px' | '404px'
      iframe.style.height = e.data.height;  // '80px' | '584px'
    }
  });
</script>

Script 标签注入

通过一行 script 标签自动创建 iframe 并注入页面，无需手动编写 iframe HTML。适合希望最小化集成代码的场景。

<!-- 只需一行代码即可嵌入客服聊天框 -->
<script>
(function() {
  var HCS_BASE = 'https://aics.toffsdev.com';

  // 创建 iframe
  var iframe = document.createElement('iframe');
  iframe.id  = 'hcs-chat-iframe';
  iframe.src = HCS_BASE + '/widget.html?key=wVv2zL3R8KnC7s86';
  iframe.setAttribute('allow', 'microphone');
  Object.assign(iframe.style, {
    position:   'fixed',
    bottom:     '0',
    right:      '0',
    width:      '80px',
    height:     '80px',
    border:     'none',
    zIndex:     '9999',
    transition: 'width 0.25s ease, height 0.25s ease',
  });
  document.body.appendChild(iframe);

  // 监听尺寸变化
  window.addEventListener('message', function(e) {
    if (e.origin !== HCS_BASE) return;
    if (e.data && e.data.type === 'argus-chat-resize') {
      iframe.style.width  = e.data.width;
      iframe.style.height = e.data.height;
    }
  });
})();
</script>

弹窗式 (popout) —— 对标 daybet / tawk.to

不在主站加载任何挂件脚本本体：宿主自制一个浮动入口按钮，点击后用 window.open 打开一个全屏独立窗口的聊天页。URL 用干净短链 /chat/<brand_key>（对标 tawk / LiveChat：路径即品牌、隐含 popout）。适合多品牌 / 多入口共用、或不想在主站注入挂件的场景，与两种 iframe 内嵌方式可并存。 本页左右两个金色圆标即为此效果（左 SIT / 右 UAT）。

<!-- 1. 宿主自制入口按钮（样式随意，纯宿主 HTML/CSS）-->
<button id="cs-entry">在线客服</button>

<!-- 2. 点击 → 新窗口打开全屏 popout 挂件（不加载任何 widget 脚本本体）-->
<script>
  document.getElementById('cs-entry').addEventListener('click', function () {
    var url = 'https://aics.toffsdev.com/chat/QguUaO9-jGxvD9BY'
      + '?lang=en'       // zh / en / fil / tl / km
      + '&mc=demo';      // 可选：非可信商户码，供坐席端归因
    window.open(url, 'toffs-chat', 'width=420,height=640');
  });
</script>

URL 形态：https://<域名>/chat/<brand_key>?lang=&mc=。旧写法 /widget.html?brand_key=…&mode=popout 仍向后兼容。弹窗外观（顶部 logo、Home 屏 banner / 促销卡、欢迎语与快捷按钮、主题色）由后台「品牌详情 → Widget 外观 / Home 屏 / 欢迎语」配置驱动，宿主侧零改动即可换肤。

配置参数

参数	说明	示例
`src`	TOFFS HCS 服务器的聊天组件地址，即 `/widget.html` 的完整 URL（需带 `key` 参数）	`https://aics.toffsdev.com/widget.html?key=...`
`key`	Widget 密钥，标识接入的项目 / 站点，并校验跨域来源；从 TOFFS HCS 后台获取	`wVv2zL3R8KnC7s86`
`HCS_BASE`	TOFFS HCS 服务器根地址（方式二中使用），用于校验 `postMessage` 来源	`https://aics.toffsdev.com`
初始尺寸	收起状态 `80×80px`（仅显示浮动按钮），展开状态 `404×584px`	—

postMessage 协议

字段	类型	说明
`type`	`string`	固定值 `"argus-chat-resize"`
`width`	`string`	iframe 目标宽度，如 `"80px"` 或 `"404px"`
`height`	`string`	iframe 目标高度，如 `"80px"` 或 `"584px"`

后端配置要求

环境变量	说明
`CHAT_ENABLED=true`	开启聊天功能（否则 `/api/chat/*` 路由不可用）
`CORS_ORIGINS`	需包含嵌入页面的域名，如 `https://yoursite.com`
`TRTC_SDK_APP_ID`	腾讯云 IM (TIM) 的 SDKAppID，用于即时通讯
`TRTC_SECRET_KEY`	腾讯云 IM 密钥，用于生成 UserSig