客服系统接入说明

运营入口

完整说明也可导出仓库中的 integration.md 发给接入方。

1. 接入前准备

向运营方索取：服务地址、site-key（前台）、agent-key（后台，勿公开）、并确认你的域名已加入 Origin 白名单。

浏览器地址栏的协议、主机、端口必须与白名单完全一致，否则挂件无法启动。

2. 访客前台（必接）

在公共布局加入（建议 </body> 前，全站一次）：

属性	必填	说明
data-site-key	是	站点密钥
data-user-id	否	业务用户 ID；客服可见；同站同 ID 跨浏览器共用会话
data-user-name	否	业务显示名；客服侧优先展示
data-hide-launcher	否	true 隐藏右下角气泡
data-open-selector	否	点击匹配元素时打开聊天

界面语言在租户管理里按站点指定，可选 English、Español、Português、中文。访客聊天窗不再提供语言切换。

登录后再补身份：

CustomerSupport.setUser({ id: String(user.id), name: user.nickname })
CustomerSupport.setUser(null) // 退出登录

JS：CustomerSupport.open() / close() / toggle()。元素加 data-cs-open 也可打开。

直接链接

不嵌脚本时，把下面的地址做成按钮或发给用户。打开后是整页客服，不需要把网站域名加入白名单。

已登录用户把身份放在查询参数里，作用与 data-user-id / data-user-name 相同：

地址里的 site 是该站点的 site-key，可在租户管理里复制。同一浏览器再次打开会回到原会话。挂件里的匿名访客和这条链接互不相通；要对上同一个人，请带上稳定的 uid。

3. 自定义打开按钮（可选）

不隐藏气泡时，页面按钮与右下角气泡可同时使用。

4. 客服后台挂件（可选）

仅放在登录后布局，不要放登录页：

也可让客服直接打开本站 客服登录，无需嵌入挂件。

5. 检查清单

• 前台 / 后台域名已告知运营方并加入白名单
• 脚本 src 指向当前可访问的服务根地址
• 访客使用本站 site-key；后台使用对应 agent-key
• 已登录用户建议传 user-id + user-name 或调用 setUser
• 真实域名下点开聊天，确认双方能收发消息

6. 常见问题

现象	处理
没有气泡 / 启动失败	检查 site-key 与 SITE_ORIGINS
换票 403	Origin 与白名单不一致（协议 / 端口）
不实时	确认走正确服务地址；Nginx 需转发 WebSocket
客服看不到昵称	传入 data-user-id / data-user-name 或 setUser

请勿把 agent-key 写进公开页面或公开仓库。