TOFFS HCS 客服聊天框集成演示

iframe 嵌入

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

<!-- 1. 在页面中放置 iframe，指向 TOFFS HCS 聊天页面 -->
<iframe
  id="chat-iframe"
  src="https://hcs.toffsdev.com/chat-widget.html"
  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://hcs.toffsdev.com';

  // 创建 iframe
  var iframe = document.createElement('iframe');
  iframe.id  = 'hcs-chat-iframe';
  iframe.src = HCS_BASE + '/chat-widget.html';
  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>

配置参数

参数	说明	示例
`src`	TOFFS HCS 服务器的聊天组件地址，即 `/chat-widget.html` 的完整 URL	`https://hcs.toffsdev.com/chat-widget.html`
`HCS_BASE`	TOFFS HCS 服务器根地址（方式二中使用），用于校验 `postMessage` 来源	`https://hcs.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