{"_id":"@alicloud-voicepica/mss-web-channel-sdk","_rev":"5-07c2d0958c6a6121285e0121675ba857","name":"@alicloud-voicepica/mss-web-channel-sdk","dist-tags":{"latest":"0.1.4"},"versions":{"0.1.0":{"name":"@alicloud-voicepica/mss-web-channel-sdk","version":"0.1.0","license":"Apache-2.0","_id":"@alicloud-voicepica/mss-web-channel-sdk@0.1.0","maintainers":[{"name":"chvin","email":"tancawe@foxmail.com"}],"dist":{"shasum":"3ae2c5270e87f2dcd924faa6a546bd42887336d9","tarball":"https://registry.npmjs.org/@alicloud-voicepica/mss-web-channel-sdk/-/mss-web-channel-sdk-0.1.0.tgz","fileCount":8,"integrity":"sha512-4F52Ld248B8ew0aUEglTDGiYkN+AtvpoGfnvZijJOKcsO5qX+04P8QTLtd8VWpy7eQ/iVNQiWM1fe5ZYHSWxGQ==","signatures":[{"sig":"MEUCIQCvgDiFMfO1fgvVzhHYp6AVA08cQv0odYKRSp/dq5gpCwIgJGb4FkcBDp3x8PLB6EDDGqMAN5qUKT2Miz/WMlb03pw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":208676},"main":"./dist/index.cjs","type":"module","_from":"file:alicloud-voicepica-mss-web-channel-sdk-0.1.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./package.json":"./package.json"},"scripts":{"dev":"tsdown --watch --no-clean","test":"vitest run","build":"tsdown","build:umd":"tsdown --config tsdown.umd.config.ts && node scripts/inline-umd-css.mjs && node scripts/gen-umd-notices.mjs && node scripts/verify-umd.mjs","typecheck":"tsc --noEmit"},"_npmUser":{"name":"chvin","email":"tancawe@foxmail.com"},"_resolved":"/private/var/folders/vd/52vhjj6946l2b2jgw2xzzsvm0000gp/T/e3740929e6936ef6bd09499ae63b4098/alicloud-voicepica-mss-web-channel-sdk-0.1.0.tgz","_integrity":"sha512-4F52Ld248B8ew0aUEglTDGiYkN+AtvpoGfnvZijJOKcsO5qX+04P8QTLtd8VWpy7eQ/iVNQiWM1fe5ZYHSWxGQ==","_npmVersion":"10.9.2","description":"mss-agent Web 渠道前端 SDK：把 Agent 对话能力嵌入客户网站。","directories":{},"_nodeVersion":"22.17.0","dependencies":{"antd":"^6.6.0","classnames":"^2.5.1","@ant-design/x":"^2.9.0","@ant-design/icons":"^6.3.2","@ant-design/x-markdown":"^2.9.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"less":"^4.9.0","react":"^19.2.8","unrun":"^0.3.1","tsdown":"^0.22.14","vitest":"^4.1.10","react-dom":"^19.2.8","typescript":"~6.0.2","@tsdown/css":"^0.22.14","@types/less":"^3.0.8","@types/react":"^19.2.17","@types/react-dom":"^19.2.3"},"peerDependencies":{"react":">=18","react-dom":">=18"},"_npmOperationalInternal":{"tmp":"tmp/mss-web-channel-sdk_0.1.0_1787626263858_0.06932818006530916","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@alicloud-voicepica/mss-web-channel-sdk","version":"0.1.1","license":"Apache-2.0","_id":"@alicloud-voicepica/mss-web-channel-sdk@0.1.1","maintainers":[{"name":"chvin","email":"tancawe@foxmail.com"}],"dist":{"shasum":"d7b0f5195aea34e8b62473c043478120f30da831","tarball":"https://registry.npmjs.org/@alicloud-voicepica/mss-web-channel-sdk/-/mss-web-channel-sdk-0.1.1.tgz","fileCount":8,"integrity":"sha512-MawLflACj84GpMH4ywEK5F2SlfRQbPMd7HWdsVvTjmUHP/AnsqeCx7fx6ziKQubf7JvP19bla6y2IACbA4OieQ==","signatures":[{"sig":"MEUCIQCaIFqrkDMTi3uXnCnR9te3l0nWhHy/tlDiKESPYgBc8AIgZk2FlcrzUSEgBoXZ9c7JsBilHITZE0/0qRmS3J8GQGw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":246656},"main":"./dist/index.cjs","type":"module","_from":"file:alicloud-voicepica-mss-web-channel-sdk-0.1.1.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./package.json":"./package.json"},"scripts":{"dev":"tsdown --watch --no-clean","test":"vitest run","build":"tsdown","build:umd":"tsdown --config tsdown.umd.config.ts && node scripts/inline-umd-css.mjs && node scripts/gen-umd-notices.mjs && node scripts/verify-umd.mjs","typecheck":"tsc --noEmit"},"_npmUser":{"name":"chvin","email":"tancawe@foxmail.com"},"_resolved":"/private/var/folders/vd/52vhjj6946l2b2jgw2xzzsvm0000gp/T/104259277630bc52471b0aa23dc03743/alicloud-voicepica-mss-web-channel-sdk-0.1.1.tgz","_integrity":"sha512-MawLflACj84GpMH4ywEK5F2SlfRQbPMd7HWdsVvTjmUHP/AnsqeCx7fx6ziKQubf7JvP19bla6y2IACbA4OieQ==","_npmVersion":"10.9.2","description":"mss-agent Web 渠道前端 SDK：把 Agent 对话能力嵌入客户网站。","directories":{},"_nodeVersion":"22.17.0","dependencies":{"antd":"^6.6.0","classnames":"^2.5.1","@ant-design/x":"^2.9.0","@ant-design/icons":"^6.3.2","@ant-design/x-markdown":"^2.9.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"less":"^4.9.0","react":"^19.2.8","unrun":"^0.3.1","tsdown":"^0.22.14","vitest":"^4.1.10","react-dom":"^19.2.8","typescript":"~6.0.2","@tsdown/css":"^0.22.14","@types/less":"^3.0.8","@types/react":"^19.2.17","@types/react-dom":"^19.2.3"},"peerDependencies":{"react":">=18","react-dom":">=18"},"_npmOperationalInternal":{"tmp":"tmp/mss-web-channel-sdk_0.1.1_1788313350087_0.20139416493145568","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@alicloud-voicepica/mss-web-channel-sdk","version":"0.1.2","license":"Apache-2.0","_id":"@alicloud-voicepica/mss-web-channel-sdk@0.1.2","maintainers":[{"name":"chvin","email":"tancawe@foxmail.com"}],"dist":{"shasum":"32f4e93c36245eceeef23e68b26cb0adc06bb8c3","tarball":"https://registry.npmjs.org/@alicloud-voicepica/mss-web-channel-sdk/-/mss-web-channel-sdk-0.1.2.tgz","fileCount":8,"integrity":"sha512-sXY3672C5tw+6sdEf6AsVhvOJfOsCTJAhJU/FVOrBmJKbQ/BJ45RNe3eM+PrAjCEKI0djgRpN2Rwq1ah1Ne+Hw==","signatures":[{"sig":"MEQCIBRlXcaZHRtZOP4f4dTc3FHGbu9s5e1WtpYwkG23NNVBAiAzLyJ1VkLow3NcEVWkWL9YSnE+Ps8Y52yWdAmTnkCCSA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":251068},"main":"./dist/index.cjs","type":"module","_from":"file:alicloud-voicepica-mss-web-channel-sdk-0.1.2.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./package.json":"./package.json"},"scripts":{"dev":"tsdown --watch --no-clean","test":"vitest run","build":"tsdown","build:umd":"tsdown --config tsdown.umd.config.ts && node scripts/inline-umd-css.mjs && node scripts/gen-umd-notices.mjs && node scripts/verify-umd.mjs","typecheck":"tsc --noEmit"},"_npmUser":{"name":"chvin","email":"tancawe@foxmail.com"},"_resolved":"/private/var/folders/vd/52vhjj6946l2b2jgw2xzzsvm0000gp/T/de7f2570fbbed334bcba2e88f908f455/alicloud-voicepica-mss-web-channel-sdk-0.1.2.tgz","_integrity":"sha512-sXY3672C5tw+6sdEf6AsVhvOJfOsCTJAhJU/FVOrBmJKbQ/BJ45RNe3eM+PrAjCEKI0djgRpN2Rwq1ah1Ne+Hw==","_npmVersion":"10.9.2","description":"mss-agent Web 渠道前端 SDK：把 Agent 对话能力嵌入客户网站。","directories":{},"_nodeVersion":"22.17.0","dependencies":{"antd":"^6.6.0","classnames":"^2.5.1","@ant-design/x":"^2.9.0","@ant-design/icons":"^6.3.2","@ant-design/x-markdown":"^2.9.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"less":"^4.9.0","react":"^19.2.8","unrun":"^0.3.1","tsdown":"^0.22.14","vitest":"^4.1.10","react-dom":"^19.2.8","typescript":"~6.0.2","@tsdown/css":"^0.22.14","@types/less":"^3.0.8","@types/react":"^19.2.17","@types/react-dom":"^19.2.3"},"peerDependencies":{"react":">=18","react-dom":">=18"},"_npmOperationalInternal":{"tmp":"tmp/mss-web-channel-sdk_0.1.2_1788399786147_0.33033414533787253","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@alicloud-voicepica/mss-web-channel-sdk","version":"0.1.3","license":"Apache-2.0","_id":"@alicloud-voicepica/mss-web-channel-sdk@0.1.3","maintainers":[{"name":"chvin","email":"tancawe@foxmail.com"}],"dist":{"shasum":"cb943363a0dcaaeed1d40fd9f0afbb48071f1a78","tarball":"https://registry.npmjs.org/@alicloud-voicepica/mss-web-channel-sdk/-/mss-web-channel-sdk-0.1.3.tgz","fileCount":8,"integrity":"sha512-eGyiaLPzLkUml0/gkw9LuJwrKBuDNg6cEWgNSXVc0kUmQTRuMZmZdcKvYkyHMIdDeaXPS+pgytNddiuxCQ4Ctw==","signatures":[{"sig":"MEUCIQCaJcEX6wIhvLWSUCPNrBcbYDLR7qxkYBPC1hwK96q7dQIgTG8DhocVlf8XL/exsg1T4MHFgIaCTXbUnWaZO7SOHaU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":272265},"main":"./dist/index.cjs","type":"module","_from":"file:alicloud-voicepica-mss-web-channel-sdk-0.1.3.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./package.json":"./package.json"},"scripts":{"dev":"tsdown --watch --no-clean","test":"vitest run","build":"tsdown","build:umd":"tsdown --config tsdown.umd.config.ts && node scripts/inline-umd-css.mjs && node scripts/gen-umd-notices.mjs && node scripts/verify-umd.mjs","typecheck":"tsc --noEmit"},"_npmUser":{"name":"chvin","email":"tancawe@foxmail.com"},"_resolved":"/private/var/folders/vd/52vhjj6946l2b2jgw2xzzsvm0000gp/T/e31bab0fbc664b0c87a4a33eae4912d2/alicloud-voicepica-mss-web-channel-sdk-0.1.3.tgz","_integrity":"sha512-eGyiaLPzLkUml0/gkw9LuJwrKBuDNg6cEWgNSXVc0kUmQTRuMZmZdcKvYkyHMIdDeaXPS+pgytNddiuxCQ4Ctw==","_npmVersion":"10.9.2","description":"mss-agent Web 渠道前端 SDK：把 Agent 对话能力嵌入客户网站。","directories":{},"_nodeVersion":"22.17.0","dependencies":{"antd":"^6.6.0","classnames":"^2.5.1","@ant-design/x":"^2.9.0","@ant-design/icons":"^6.3.2","@ant-design/x-markdown":"^2.9.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"less":"^4.9.0","react":"^19.2.8","unrun":"^0.3.1","tsdown":"^0.22.14","vitest":"^4.1.10","react-dom":"^19.2.8","typescript":"~6.0.2","@tsdown/css":"^0.22.14","@types/less":"^3.0.8","@types/react":"^19.2.17","@types/react-dom":"^19.2.3"},"peerDependencies":{"react":">=18","react-dom":">=18"},"_npmOperationalInternal":{"tmp":"tmp/mss-web-channel-sdk_0.1.3_1788662133469_0.794513665875255","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"@alicloud-voicepica/mss-web-channel-sdk","version":"0.1.4","description":"mss-agent Web 渠道前端 SDK：把 Agent 对话能力嵌入客户网站。","license":"Apache-2.0","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./package.json":"./package.json"},"publishConfig":{"access":"public"},"dependencies":{"@ant-design/icons":"^6.3.2","@ant-design/x":"^2.9.0","@ant-design/x-markdown":"^2.9.0","antd":"^6.6.0","classnames":"^2.5.1"},"peerDependencies":{"react":">=18","react-dom":">=18"},"devDependencies":{"@tsdown/css":"^0.22.14","@types/less":"^3.0.8","@types/react":"^19.2.17","@types/react-dom":"^19.2.3","less":"^4.9.0","react":"^19.2.8","react-dom":"^19.2.8","tsdown":"^0.22.14","typescript":"~6.0.2","unrun":"^0.3.1","vitest":"^4.1.10"},"scripts":{"build":"tsdown","build:umd":"tsdown --config tsdown.umd.config.ts && node scripts/inline-umd-css.mjs && node scripts/gen-umd-notices.mjs && node scripts/verify-umd.mjs","dev":"tsdown --watch --no-clean","test":"vitest run","typecheck":"tsc --noEmit"},"_id":"@alicloud-voicepica/mss-web-channel-sdk@0.1.4","_integrity":"sha512-kS658UqwURUZiqGyn0/YzhSufQEojIC23OQPUEJdyyztnfNT/9Hs2eLs4XwcR6C+F1rKl/sN5PfxcX7Jlds4Pw==","_resolved":"/private/var/folders/vd/52vhjj6946l2b2jgw2xzzsvm0000gp/T/43a7722f23078e58c59d029be81245ff/alicloud-voicepica-mss-web-channel-sdk-0.1.4.tgz","_from":"file:alicloud-voicepica-mss-web-channel-sdk-0.1.4.tgz","_nodeVersion":"22.17.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-kS658UqwURUZiqGyn0/YzhSufQEojIC23OQPUEJdyyztnfNT/9Hs2eLs4XwcR6C+F1rKl/sN5PfxcX7Jlds4Pw==","shasum":"7386fb471fef0bf222c9bd814e780d00fb9ae481","tarball":"https://registry.npmjs.org/@alicloud-voicepica/mss-web-channel-sdk/-/mss-web-channel-sdk-0.1.4.tgz","fileCount":8,"unpackedSize":349182,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCu5fyzbqpEpMU1328Y4z2SgeXcYuVxUxz7bMgMe0W+EwIhALOOkq2ve8sDamcP1AyKbACTDdWWS0nfL07Izhs05Fpi"}]},"_npmUser":{"name":"chvin","email":"tancawe@foxmail.com"},"directories":{},"maintainers":[{"name":"chvin","email":"tancawe@foxmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mss-web-channel-sdk_0.1.4_1789112023832_0.9888805877307185"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-25T02:51:03.647Z","modified":"2026-09-11T07:33:44.170Z","0.1.0":"2026-08-25T02:51:04.012Z","0.1.1":"2026-09-02T01:42:30.239Z","0.1.2":"2026-09-03T01:43:06.319Z","0.1.3":"2026-09-06T02:35:33.636Z","0.1.4":"2026-09-11T07:33:43.981Z"},"license":"Apache-2.0","description":"mss-agent Web 渠道前端 SDK：把 Agent 对话能力嵌入客户网站。","maintainers":[{"name":"chvin","email":"tancawe@foxmail.com"}],"readme":"# @alicloud-voicepica/mss-web-channel-sdk\n\nmss-agent Web 渠道前端 SDK。把 Agent 对话能力嵌入你自己的网站：**你的后端断言用户身份并换取令牌**，SDK 拿令牌完成整段对话（连接、重连、历史、幂等、刷新都在 SDK 内部）。\n\n两种接入形态，能力完全一致，按站点技术栈选一种：\n\n| 形态 | 适用 | 宿主依赖 |\n|---|---|---|\n| npm 包 | React 站点 | 自备 `react` / `react-dom` >= 18 |\n| `<script>` / UMD | 任意站点（含无框架、React 17 及以下） | 无，React 与 antd 都在产物里 |\n\n## 快速开始（React / npm 包）\n\n```bash\nnpm i @alicloud-voicepica/mss-web-channel-sdk\n```\n\n```tsx\nimport { WebChat } from '@alicloud-voicepica/mss-web-channel-sdk'\n\n// 两个回调都打你自己的后端；SDK 不持任何阿里云凭据，也不直调 POP。\nconst getToken = () => fetch('/api/webchat/token', { method: 'POST' }).then((r) => r.json())\nconst refreshToken = (rt: string) =>\n  fetch('/api/webchat/token/refresh', {\n    method: 'POST',\n    headers: { 'content-type': 'application/json' },\n    body: JSON.stringify({ refreshToken: rt }),\n  }).then((r) => r.json())\n\n<WebChat channelId=\"<web 渠道 ID>\" getToken={getToken} refreshToken={refreshToken} />\n```\n\n## 快速开始（`<script>` / UMD）\n\n一个 `<script>` 即可，**不需要另外引 React、antd 或任何 CSS**（样式在产物内运行时注入）。\n\n```html\n<div id=\"mss-agent-chat\"></div>\n\n<script src=\"https://g.alicdn.com/convai-platform/mss-agent-fe-sdk/0.1.0/umd/index.js\"></script>\n<script>\n  // 构造入参与 React 组件的 props 完全一致\n  const mssAgent = new window.MssAgentWebChannelSDK.WebChat({\n    channelId: '<web 渠道 ID>',\n    getToken: () => fetch('/api/webchat/token', { method: 'POST' }).then((r) => r.json()),\n    refreshToken: (rt) =>\n      fetch('/api/webchat/token/refresh', {\n        method: 'POST',\n        headers: { 'content-type': 'application/json' },\n        body: JSON.stringify({ refreshToken: rt }),\n      }).then((r) => r.json()),\n  })\n\n  mssAgent.render({ parentNode: document.getElementById('mss-agent-chat') })\n</script>\n```\n\nURL 里的 `0.1.0` 是版本号，按需替换。\n\n脚本执行后全局挂 `window.MssAgentWebChannelSDK`，其下的 `WebChat` 是一个可 `new` 的类：\n\n| 方法 | 说明 |\n|---|---|\n| `new WebChat(options)` | `options` 与 React 组件的 props 同一份契约（见下）。只创建实例，此时还不发请求 |\n| `.render({ parentNode })` | 挂载到 `parentNode`（DOM 元素）并开始会话，返回实例本身。SDK 在 `parentNode` 下新建自己的容器节点；浮层形态（`modalMode` / `drawerMode`）下可省参，缺省 `document.body` |\n| `.update(patch)` | 浅合并新的入参并重渲染（如换一套 `style`）。走 React 重渲染、**不断线**；未挂载时只更新内部值 |\n| `.destroy()` | 卸载组件、移除自建容器、断开连接。未挂载时调用是空操作 |\n| `.mounted` | 当前是否已挂载 |\n\n行为约定：\n\n- **同一实例只有一个父节点生效**：重复 `render` 到同一父节点是幂等的（不断线、不重建）；`render` 到另一个父节点会先从原父节点卸载。\n- `destroy()` 之后仍可再 `render`，但**会话会从头开始**（重连、重拉配置与历史）。所以「展开 / 收起」请用 CSS 显隐控制，不要 `destroy` + `render`。\n\n## 接入参数\n\n`WebChat` 的 props（= UMD 构造入参）：\n\n| 参数 | 类型 | 必填 | 说明 |\n|---|---|---|---|\n| `channelId` | `string` | 是 | 管控台创建的 web 渠道 ID。不是密钥，可以出现在页面里 |\n| `getToken` | `GetTokenFn` | 是 | 取令牌，见下节 |\n| `refreshToken` | `RefreshTokenFn` | 是 | 续期令牌，见下节 |\n| `style` | `CSSProperties` | 否 | 覆盖默认尺寸（面板默认 380 × 520），如 `{ width: '100%', height: 600 }` |\n| `className` | `classnames` 的 `Argument` | 否 | 追加到根节点的类名，见下方 |\n| `modalMode` / `modalProps` | `boolean` / `Omit<ModalProps, 'children'>` | 否 | 弹窗形态（与 `drawerMode` 同时开启时它优先）；属性全量透传给 antd `Modal`，显影传 `open` |\n| `drawerMode` / `drawerProps` | `boolean` / `Omit<DrawerProps, 'children'>` | 否 | 抽屉形态；属性全量透传给 antd `Drawer`（宽度 `size` / 方位 `placement` / 显影 `open`）|\n| `quickReplyCallback` | `Record<string, { callback: () => void }>` | 否 | 回调型快捷短语的处理器，键是管控台填的回调标识；未注册时按钮照常展示、点击无反应 |\n\n三种展示形态（内嵌 / 弹窗 / 抽屉）的完整用法、默认值与注意事项见 [`wiki/web-channel-client-npm.md`](../../wiki/web-channel-client-npm.md)。\n\n### className\n\n内部用 [`classnames`](https://www.npmjs.com/package/classnames) 合并，所以它可以是该包支持的**任意形态**：\n\n```tsx\n<WebChat className=\"my-chat\" />                                  {/* 字符串 */}\n<WebChat className={['my-chat', dark && 'my-chat--dark']} />      {/* 数组，假值自动丢弃 */}\n<WebChat className={{ 'my-chat': true, 'my-chat--dark': dark }} />{/* 映射对象 */}\n```\n\n传入的类名是**追加**，SDK 自己的根类 `mss-webchat` 不会被顶掉。复写外观可以直接覆盖\n`.mss-webchat*` 这组选择器，也可以拿自己传的类名提权重（如 `.my-chat .mss-webchat__header`）。\n\n## 两个令牌回调的契约\n\nSDK 不认识阿里云凭据，令牌一律由你的后端签发后交给它：\n\n```ts\ntype GetTokenFn = () => Promise<WebChatToken>\ntype RefreshTokenFn = (refreshToken: string) => Promise<WebChatToken>\n\ninterface WebChatToken {\n  /** 访问令牌，SDK 用它调用运行面与建立连接。 */\n  accessToken: string\n  /** 续期令牌，SDK 会存下来，到期前作为 refreshToken 回调的入参。 */\n  refreshToken?: string\n  /** accessToken 的剩余有效期，单位秒（相对值，不是时间戳）。 */\n  expiresIn: number\n  /** refreshToken 的剩余有效期，单位秒。 */\n  refreshExpiresIn?: number\n  /** SDK 直连的运行面基址，由令牌接口按环境下发。 */\n  runtimeEndpoint: string\n}\n```\n\n**`getToken()`**\n\n- 入参：无。\n- 返回：`Promise<WebChatToken>`。\n- 由你的后端持 AK/SK 调用 OpenAPI `GenerateWebChannelToken` 换取，**响应字段名与上面一致，后端原样透传即可**。\n- **用户身份由后端断言**（登录态映射成外部用户标识），页面不传身份、SDK 也不接受——传什么都不会被采信。\n- 首次挂载调用一次；SDK 同时把响应里的 `runtimeEndpoint` 记在当前实例内存中，后续 HTTP 与 WebSocket 都使用该地址。\n- `runtimeEndpoint` 由平台服务端按环境下发：预发为 `https://pre-mss-agent.biz.aliyun.com`，线上为 `https://mss-agent.biz.aliyun.com`；客户前后端都不配置、不覆盖。\n\n**`refreshToken(currentRefreshToken)`**\n\n- 入参：`string` —— SDK 当前持有的续期令牌（即上一次返回的 `refreshToken`）。\n- 返回：`Promise<WebChatToken>`，对应后端调用 OpenAPI `RefreshWebChannelToken`。\n- **滑动续期**：响应里的新 `refreshToken` 必须一并返回，SDK 会用它覆盖本地值；只续期、**不改变用户身份**。\n- 由 SDK 自己择时调用（`accessToken` 到期前 60s，以及遇到 401 时），你不需要设定时器。\n\n两个回调都用 `reject` / `throw` 表达失败即可：SDK 会展示可重试的提示，不会静默假装在连接。\n有效期一律用响应里的相对秒数计时，**SDK 不解析 JWT 的 `exp`、不依赖宿主机时钟**。\n\n## Server 接入示意（Node.js）\n\n浏览器只调用客户自己的 Node.js 服务；Node.js 持 AK/SK 调用 `GenerateWebChannelToken` / `RefreshWebChannelToken`，并将包含 `runtimeEndpoint` 的响应原样返回。完整可运行实现见 [`examples/demo-server/src/token-source.ts`](../../examples/demo-server/src/token-source.ts) 与 [`server.ts`](../../examples/demo-server/src/server.ts)。\n\n```ts\nimport openApi, { Config, OpenApiRequest, Params } from '@alicloud/openapi-client'\nimport { RuntimeOptions } from '@alicloud/tea-util'\nimport express from 'express'\n\nconst client = new openApi.default(\n  new Config({\n    accessKeyId: process.env.MSS_POP_ACCESS_KEY_ID,\n    accessKeySecret: process.env.MSS_POP_ACCESS_KEY_SECRET,\n    endpoint: process.env.MSS_POP_ENDPOINT,\n    regionId: 'cn-hangzhou',\n  }),\n)\nconst channelId = process.env.MSS_WEB_CHANNEL_ID!\n\nasync function callTokenApi(action: string, suffix: string, body: Record<string, unknown>) {\n  const params = new Params({\n    action,\n    version: '2026-06-15',\n    protocol: 'HTTPS',\n    method: 'POST',\n    authType: 'AK',\n    style: 'ROA',\n    pathname: `/web-channels/${encodeURIComponent(channelId)}/tokens${suffix}`,\n    reqBodyType: 'json',\n    bodyType: 'json',\n  })\n  const response = await client.callApi(params, new OpenApiRequest({ body }), new RuntimeOptions({}))\n  const payload = response.body as { data?: unknown; Data?: unknown }\n  return payload.data ?? payload.Data ?? payload\n}\n\nconst app = express()\napp.use(express.json())\napp.post('/api/webchat/token', async (_req, res) => {\n  res.json(await callTokenApi('GenerateWebChannelToken', '', { externalUserId: 'customer-user-id' }))\n})\napp.post('/api/webchat/token/refresh', async (req, res) => {\n  res.json(await callTokenApi('RefreshWebChannelToken', '/refresh', { refreshToken: req.body.refreshToken }))\n})\napp.listen(7101)\n```\n\n服务端环境变量只放渠道 ID、POP endpoint 与 AK/SK；`RUNTIME_ENDPOINT` 是 mss-agent 服务端的部署配置，不属于客户 Node.js 配置。\n\n## 外观配置\n\n名称 / 头像 / 主题色 / 欢迎语 / 输入框引导语 / 快捷短语都来自**管控台的渠道配置**，\n由 SDK 自己拉取（`GET /webchat/config`），宿主页面不需要传，改配置发布后刷新页面即生效。\n\n快捷短语分三种类型：发送消息、打开链接、前端回调。只有**前端回调**需要宿主页面配合：用 `quickReplyCallback`\n按管控台填的回调标识注册处理器，详见\n[`wiki/web-channel-client-npm.md`](../../wiki/web-channel-client-npm.md)。\n\n## 依赖形态与产物\n\n- npm 形态：`react` / `react-dom` 是 **peerDependencies**（`>=18`，`@ant-design/x` 的硬要求）；\n  `antd` / `@ant-design/x` / `@ant-design/x-markdown` / `@ant-design/icons` / `classnames` 是**直接依赖**，\n  你无需自行安装，也不必与站点自己的 antd 版本对齐。\n- UMD 形态：上述依赖**全部内置**，宿主页面零依赖，也不会与站点已有的 React / antd 版本冲突。\n- 产物：ESM + CJS + `d.ts`（npm）、单文件 `umd/index.js`（`<script>`，样式已内联）。\n- 许可：Apache-2.0（版权 Alibaba Cloud）。UMD 产物内置了第三方代码，构建时会同目录生成\n  `THIRD-PARTY-NOTICES.txt`（依 sourcemap 算出实际内置的包），上 CDN 时需跟 `index.js` 一起发。\n\n## 能力边界\n\n已支持：\n\n- **令牌生命周期**：提前刷新（`expiresIn - 60s`）、401 换令牌重试一次、refresh 失败回落 `getToken`、\n  新 `refreshToken` 覆盖本地值（滑动续期）。\n- **配置驱动渲染**：启动先拉渠道配置（拉不到就停在可重试提示，不假装在连）；欢迎语与快捷短语本地渲染、不落库。\n- **上行**：`POST /webchat/messages` 带 `clientMsgId` 幂等键；先乐观渲染再标受理结果。\n- **下行**：WS 首帧鉴权、25s 心跳、指数退避重连（封顶 30s + 抖动）、重连后按序号补拉。\n- **历史**：首屏 / 上翻（滚到顶部自动 + 「加载更多历史」按钮兜底）/ 断线补拉。\n- **等待体验**：typing indicator + 180s 兜底超时（只提示并开放重发，**不取消请求**，晚到的回复照样渲染）。\n\n消息形态支持文本（含 markdown）渲染，图片 / 文件 / 语音上传与卡片渲染暂不支持，服务端会把卡片降级成文本下发。\n","readmeFilename":"README.md"}